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ABOUT THIS BOOK 


This reference manual describes the Common Code, a package of PASCAL functions 
and procedures for formatting information and displaying it on the screen. I[t 
also contains routines for manipulating character strings and bytes of memory. 


This book relies upon the information contained in other Compass Computer 
Manuals. The code in this manual conforms to the PASCAL language as it is 
described in the PASCAL-84 User's Guide. It assumes an operating system 
environment as defined by the GRiD Operating System (GRiD-O05) Reference 
manual, The methods for linking and loading the routines are described in the 
Program Development Guide. 


If you plan to use the Common Code to write programs that conform to the 
software requirements of GRiD Systems Corporation, be sure to see the GRiD 
Mangement Tools Reference manual. It shows GRiD's programming conventions in 
practice, 


The first two chapters of this manual introduce the Common Code and GRiD‘s 
programming conventions for menus, forms, and tables. Chapters 3 and 4 
describe data structures used by Common Code routines and the characteristics 
of data files used by GRiD applications. Chapters 3 to 11 provide a summary 
of the procedures: related procedures are grouped together, allowing you to 
obtain an overview of the routines available. Chapter 12 lists al] of the 
Common Code procedures in alphabetical order and provides a detailed 
description of each procedure. Use this chapter as the standard reference 
section once you are generally familiar with the routines that are available. 


Appendix & lists the include files for the Common Code routines. Appendix B 
lists example programs for data driven forms and menus and appendix C 
describes an alternate method for developing menus and forms. 


Additional appendices providing more examples of the use of Common Code 
routines will be available in several months. To obtain a new version of this 
manual which includes up-to-date examples, send in the "Important Notice” at 
the front of this manual. 
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CHAPTER 11 INTRODUCTION 


This chapter introduces the Common Code package, and shows how the Common Code 
routines relate to GRiD’s user interface and application programs. The Common 
Code comprises a nueber of subroutine packages, and this chapter explains 
their relation to one another. 


THE COMMON CODE: A COMMON USER INTERFACE 


BRiD applications have been designed for similarity in appearance and 
operation. This resulted from a conscious decision by GRID to produce 
software that is easy to use and to learn to use. When applications have 
similar or identical commands, the user has to learn the commands only once -- 
from then on, all new learning is based upon what the user is already familiar 
with. 


This approach is the basis of the GRID user interface. The consistent 
interface is the common feature that makes a data base as easy to use as a 
text editor. 


With this design in mind, it was logical for GRiD to put these common features 
into a single software package -- the Common Code. The Common Code provides 
the data structures and procedures for maintaining a consistent user interface 
among a variety of applications. It provides the mechanisms to implement the 
"ring" around the applications. 


Figure 1-1 shows the major packages of the Common Code. The character string 
package and window graphics package form the basis upon which all] else is 
defined. 


NOTE: The window graphics package was originally part of the Common Code 


but is now part of the GRiD Operating System {GRiD-05). Refer to the 
GRiD-O0S Reference manual for a description of window graphic routines. 
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Fields, tables, and menus/forms provide sophisticated mechanisms for 
displaying and formatting text on the screen. The features of each package 
are discussed below. 
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Figure 1-1. Major Packages of the Common Code 8 


STRING MANIPULATIGN 


The string package consists of routines for processing text characters. The 
routines offer greater flexibility than many comparable string packages. 


It features: 
® Strings up to 65535 characters long 
o A full range of string functions and numerical conversions 
o Literal strings 


o Dynamic allocation/deallocation of strings to save memory space 
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MENUS AND FORMS 


With these routines, you can send and receive data from the user by means of 
menus and forms. The user can type input or choose a predefined item from a 
list without unnecessary typing. 


The user can confirm only one item on a menu. With a form, the user can set 
several items at once, either by choosing a setting or typing a new one. 


xchange tor another rile 


Include 5 file 
Write to a file 


Append 2 file 
Erase a file 
Shou characteristics of a file 


Sample: Select item and contirn 


Saaple Menu 


Editable numeric field te 
Choice only field irst choice 


Editable-choice field A choice 


Editable real number field 5.8006 
Typeface System-wide 
Printer EpsonFx168 
Plotter HP 


sample Fill in forma and contirn 


Saaple Fora 
The menu and form package has these features: 


o Movement and editing within the menu or form is controlled completely 
by the Common Code 


o Scrolling is enabled automatically for large menus and foras 

o Menus and forms are allocated dynamically 
FIELD FORMATTING 
The field package lets you format text characters within a rectangular box 
(called a field) and display it on the screen. Each rectangular field can be 


formatted and displayed separately from any others. 


Specifically, it includes routines to 
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o Display a blinking, triangular text cursor 


o Facilitate cursor movement with arrow keys, BACKSPACE, and 
CODE-BACKSPACE (erases previous word) 


o Outline and highlight individual fields 

o Left-align, right~align, or center text within a field 

o Format multiple lines in a field, with word-wrapping 

o Specify individual fields as user-editable or display-only 


o Allocate fields dynamically 


TABULAR FORMATTING 

The table routines let you group several fields into a table and manipulate 
thea together. With these routines, numerical and character data are 
formatted so that users can examine and edit them easily. 


The table code has these features: 


o All field formatting functions are available for every data cell in 
the table 


o A text cursor and cell outline can be moved from cell to cell to show @ 
the field being edited 


o Text and cells can be duplicated, erased, moved, and inserted with 
built-in functions 


o The user can select portions of the table as operands for commands 
o Selections are highlighted automatically 
o Automatic scrolling is available 


o Tables are allocated dynamically 


HIERARCHY OF THE COMMON CODE 


The Common Code packages are designed to build upon one another. Figure 1-2 
shows the hierarchy of these packages. 
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Hens. Forms 


Messages-Prompts 


Tables 


Figure 1-2. Hierarchy of the Common Code 


Each outer level depends upon the data structures and procedures of an inner 
level. They have been left separate so that you can program at the level of 
detail and sophistication required by each application. The Common Code can 
do as little as displaying a single bit on the screen, or as much as 
managing, displaying, and updating several data structures in real time. When 
reading this manual, keep this structure in mind. The sequence in which the 
routines are presented in the following chapters do not, however, strictly 
follow this hierarchical approach. Instead, we present the basic structures 
and routines that you need to implement commands, messages, prompts, #enus, 
and forms. This lets you begin using the most widely used capabilities 
provided by Common Code without becoming totally familiar with some of the 
undertying structures. We discuss fields and tables last because, although 
they profide the underlying structure for menus and forms, you usually need 
not use them directly unless you are working on a cell-based application such 
as a spreadsheet. 
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CHAPTER 21 THE USER INTERFACE 


This chapter describes the major features of the user interface for GRiD 
software products. It provides the necessary background for using the Comaon 
Code to construct user interfaces that are compatible with GRID software 
products. The terminology introduced in this chapter is used throughout the 
manual. 


Many of the capabilities provided by the Common Code can be utilized without 
understanding some of the underlying or auxiliary capabilities. For example, 
you can easily implement menus and forms just like those used in GRiD 
applications without delving into the complexities of cells and fields. For 
this reason, the chapters in this book present a few basic routines, such as 
string handling routines, that are needed to use menus and forms, but save 
explanations of cells and fields until the later chapters. This approach 
should let you begin using some of the powerful features of the Common Code 
immediately. When you feel comfortable with these capabilities, such as 
Messages, Commands, menus, and forms, you can begin exploring the more complex 
functions and procedures provided by the Common Code. 


THE OPERATING ENVIRONMENT 


The Common Code is designed to operate specifically with the GRiD Operating 
System (GRiD-0S), a multiprocessing system, 


o It is designed to be reentrant so that several concurrent processes 
can use it at once. 


o Different processes are assigned different areas, or windows, on the 
screen to operate. Each window represents a separate process. The 
Common Code controls the display within each window. Hence, all data 
and graphics are displayed relative to a window, and never defined 
upon the absolute size of the screen. 
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o All data structures are allocated and deallocated dynamically to save 
memory space for other applications to run. This is the rationale P 
behind the extensive use of pointers in the field, table, and @ 
menu/form packages. 


CODE COMMANDS 


The user causes the computer to perform an action by pressing a CODE key 
command, such as CODE-D for Duplicate, 


The CODE key is a modifier key, like CTRL or SHIFT. The CODE command 
characters are not displayed on the screen; they are carried out directly. 
GRID chose the CODE key for commands so that CTRL and SHIFT would be left free 
for commands to existing terminal emulators and timesharing systems. 


Figure 2-1 shows the syntax of a typical command. 
{EEE 
Hove to iten 
Forn appears: 
Fill in Forn 
elect. text 


or cells 


Figure 2-1. Syntax of a Typical Command 


The user moves the cursor and outline to the text or cell to be acted on by 
the command, After pressing the CODE key command, the user faces one of these 
options, depending on the command: 


o To aove to an item on a menu. 
o To fill in a fora. 
o To select additional text or cells by pressing arrow keys. 


These three options are described later. The user then presses CODE-RETURN to 
confirm the menu item, form, or selection. If the command requires additional 
parameters, it will display additional menus, forms, or sessages requesting a 
selection. 
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MESSAGES 


Messages and prompts to the user are displayed in lines at the bottom of the 
screen. The messages or prompts are highlighted within a display-only field 
that the user cannot move to. They are centered within the field. 


Messages should be programmed to disappear upon the next keystroke. Command 
prompts should remain displayed until the user confirms or cancels the 
command. Messages and prompts have this appearances 


<Command name>; <Prompt> 
Duplicate: Make a selection.and confira 
Properties: Fill in form and confira 


Transfer: Select item and confira 


THE FLOW OF CONTROL 


GRiD applications are designed to be “modeless". That is, the user does not 
have to press special keys to enter Edit Mode, Command Mode, Retrieve Mode, 
etc. In any GRID application, the user sisply types text (without having to 
enter an Edit Mode) or presses a command key. 


The user can always terminate a command at any point. At each step in a 
command, whether confirming a menu item, filling in a form, or making a 
selection, the user can press ESC and the command is aborted. The user can 
then type text or issue any command. 


Pressing a command key during another command preeapts the pending command and 
starts a new one. By pressing one command key, the user can stop any command 
and begin any other one. 


COMMON COMMANDS 
The real advantage of the leveraged learning interface is that the commands in 
different applications have similar names and syntax. Table 2-1 below shows 


these sisilar commands. Many of these are available as functions in the 
Common Code. 
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KEY COMMAND GRiDPlot GRiDFile GRiDWrite GRiDPlan GRiDManager @ 


CODE-A ACCESS x x x x x 

CODE-B BEGIN x x x x 

cobe-C COLUMN x x x 

CODE-D DUPLICATE x x x x x 

CODE-E ERASE x x x x Xx 

CODE-F FIND x x 

CODE-H HEADINGS x x 

CODE-1 INSERT x x x 

CODE-J JUMP Xx x 

CODE-M MOVE x x x x x 

CODE-0 OPTIONS x x x x x 

CODE-P PROPERTIES xX x x 

CODE-8 BUIT x x x x 

CODE-R ROW x x x 

CODE-S SUBSTITUTE x x 

CODE-T TRANSFER Xx x x x x 

CODE-U USAGE x x x x Xx 

CODE-W WILDCARD x x 

CODE-ESC CANCEL x x x x x 

CODE-RETURN CONFERM Xx x x x x 

CODE-? HELP x x x Xx Xx 

eaecssceceeseeeesscss gaseecsnsscesssess 
Table 2-1. Common Commands 

The arrow keys are standard across applications too. See Appendix D for a @ 


discussion of the keys and the Common Code procedures to control thea. 
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MENUS AND FORMS 
® Commands can request data from the user by presenting a menu or a form, With 


amenu, the user selects a single value as input to the Compass. Forms allow 
the user to give the computer several values at once. 


Menus 


See Figure 2-2 for a sample GRiD menu. All GRiD menus resemble this one. 


hg! 

Include a File 
Mrite te a Pile 
Append to a File 
Erase a File 
Shou characteristics of a Pile 
Fornat. 

Print 


pm teotyaie 


Heru Itens Hessage Line Outline 


Figure 2-2. A Sample GRiD Menu 


@® A menu consists of: 


Menu items A vertical list of objects or operations, such as commands, file 
titles, or storage media. By confirming an item, the user 
tells the Compass to operate with that item instead of the 
others. The items are display-only fields that the user cannot 
aodify. 


Butline A moving indicator that rests upon the current item. A 
triangular cursor never appears within this outline, because 
text cen never be typed into a menu. 

Message Line An informational message instructing the user as to what action 
to take with the menu. 
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Example 


Within a word processing program, the user presses CODE-T to transfer a file 
te a storage medium. The menu shown below appearst 


ae me a ara 


Include a File 

Write to a File 

Append 10 a File 

Erase a File 

Shou characteristics of a File 
Fornat 

Print 


The user presses RETURN three times to move the outline to the item titled 
Write to a file. Users can move the outline as much as they like before 
confirming an item, 


Save this file 
Exchat 
Inclu 


Hppend to a 

Erase a File 

Show characteristics of a File 

Fornat a) 
Print 


The user presses CODE-RETURN. The word processing program finds out which 
item was confiraed and performs the operation. Gnly one item can be confiraed 
at a time. 


lf the user presses ESC or another comaand key, the menu disappears and no 
operation is performed. 


Foras 


See Figure 2-3 for a representative BRiD form. Most GRiD foras resemble this 
one. Forms are different from menus, for these reasons: 


o Most forms let users change the settings of several items. Menus let thea 
confirm only one itea. 

o Users can type their own settings. Many forms do not limit them to 
predefined choices . 

o When users press CODE-RETURN, they confirm the settings of all the form 
items, not just the outlined setting. 
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Forn Itens 


A form consists of: 


Form items 


Settings 


Outline 


Choice band 


Choices 


Highlighted box 


~~" Highlighted Eox 


Choices 


Standard colunn width & 
ghendend:slisneent "i Sd) 
Standard Fornat nteger 


Current TypePace 
+ 


Choice Band 


i 
i 


ob 


Systen-vide 


+ , 
ERB for and contirn | 


H 
Sett ings Outline 


Figure 2-3. & Sample GRiD Form 


Labels which identify the data to be modified. Each item 
has a setting associated with it. These are display-only 
fields that the user cannot move into. 


The actual values that the user types or chooses from the 
Choice band. Application programs read these values and 
operate on them. These are editable, choice, or 
editable-choice fields, depending on the application. 


A moving indicator that surrounds the setting currently 
being modified. RETURN moves it down and SHIFT-UpArrow 
moves it up. 


If the outlined setting contains a blinking cursor, users 
can type their own value for that setting. 


Located at the top of the form, it contains the choices 
associated with an item. As the user moves from item to 
item, the choices in the choice band change. The choices 
appear either horizontally or vertically. (Forms without 
choices do not have a choice band.) 


Predefined values for a setting, which appear in the 
choice band. The highlighted choice appears within the 
outline automatically. It is the value for the outlined 
setting, The choices are display-only fields. 


Indicates the choice that appears in the outlined setting. 
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Pressing the arrow keys moves it among choices. 


Exaaple 


In a tabular worksheet program, a user presses CODE-O to adjust the 
worksheet‘s options. This form appears, with these initial values: 


Left Center 


a 
Standard Fornat. nteger 


Standard column width $ 


Shou grid? Yes 
Evaluation order By rous 
Precision 15-digit Real 


Current typeface Systen-uide 


trons Fill in corn and confirm 


Gi) 


The outline surrounds the setting associated with the Standard Alignment item. 
This setting is a choice field. In the choice band, the highlighted box rests 
upon Right. Right also appears within the outline. 
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The user presses LeftArrow once, and the highlighted box moves to Center. The 
outlined setting now contains Center as well; the Common Code does this 
automatically. 


Left Right 


Standard alionnent [enter 
Standard Fornat nteger 
Standard column width & 


Show grid? tes 
Evaluation order By rous 
Precision 15-digit Real 
Current typeface Susten-uide 


Detions Fill in Form and confirm 


The user presses RETURN to move the outline to another setting. New choices 
appear in the choice band. The user presses LeftArrow twice, and the 
highlighted box moves to Decimal Places. The setting is an editable-choice 
field, so a blinking cursor appears in the outline. The user types a number. 


Integer $ Scientific 


Standard alignnent Center 
Standard format 
Standard colunn width 


Shou grid? Yes 
Evaluation order By rous 
Precision 1S-disit Real 
Current typeface Susten-wide 


Fill in form and confirn 


The user presses RETURN again. The choice band is now empty, but the blinking 
Cursor appears within the outline. The setting is an editable field, The 
user presses BACKSPACE to erase the initial value, and types another value. 


NOTE: Wherever the blinking cursor appears, the Common Code lets the user 


modify text using arrow keys, BACKSPACE, and CODE-BACKSPACE (erase previous 
word). 
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Standard alignment Center 
Standard Pornat 


Standard colunn width & j 
Show grid?- es 


Evaluation order By rous 
Precision 1S-digit Real 
Current typeface Susten-uide 


Options: Fill in Form and confirn 


Pressing CODE-RETURN now returns the cursor and outline ta their previous 
context, the worksheet program. The worksheet program could then retrieve the 
new settings of the form and operate upon them. The form disappears. 


lf the fora had appeared in the course of a command, the command would 
continue. 


Pressing ESC or another CODE command would return the outline to the worksheet 
program (canceling any pending command), wrt the form would retain all its old 
settings. 


FORMATTING INFORMATION 


&n essential function of the Common Code is to format information for display 
on the screen within an application window. It provides a sophisticated 
mechanism for putting raw text and data into formatted fields. 


Fields 


To the user, a field is a rectangular area on the screen that contains text or 
numeric values. It can be filled in by the user or the system. 


To the prograsaer, a field is a data structure that contains a text string and 
formatting information for that text. The Common Code provides procedures for 
formatting the text and displaying the text on the screen. 


The contents of a field can be left-aligned, right-aligned, or centered. 
Fields can contain more than one line of text. There are four types of 
fields, designed to protect data or enable the user to interact with it. 


Editable Editable fields allow the user to edit their values by 
typing, backspacing, or pressing arrow keys to move within 
the tield. 

Display-Gnly The user cannot alter the values of these fields. 

Choice Choice fields can contain only settings from a predefined 


list. They are used only within forms, as described later. 


Editahle-Choice Editahle-choice fields can contain settings chosen from a 
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predefined list, or the user can edit their values by typing, 
backspacing, or pressing arrow keys. They occur only in 
forms, as described later. 


Tables 


Tables are collections of fields gathered together as a matrix. They are 
convenient for displaying large amounts of numerical data or for putting text 
into a tabular format. 


Tables consist of editable fields, though the fields could be modified to 
become display-only in order to protect the field contents. Each field in a 
table is called a cell. 


Tables are easier to use than individual fields. The Comaon Code has defined 
procedures for moving from cell to cell, and for controlling the cell that is 
to be edited. Automatic scrolling has been developed for tables, and several 
cell functions have been defined to operate upon selections of cells. 


EDITING INFORMATION 


The Comaon Code provides several mechanisms for editing information within a 
field: cursor control, code commands, menus and forms, text and cell 
selections, and screen messages. 


Cursor Control 


For editing within fields, the Common Code provides routines to generate a 
blinking triangular cursor, which is placed between character positions in @ 
field. 


For applications with more than one field on the display, the Common Code has 
routines to outline the field currently being edited. The table package has 
routines for moving both the cursor and the cell outline, and for keeping 
track of the “current celi”, 


The user moves the cursor and cell outline by pressing arrow keys. Appendix G 
lists these arrow keys along with the Common Code routines that control their 
operation. 


The table package also has built-in functions for scrolling. {if a user tries 
to move the cursor and cell outline outside of a scrolling boundary, the 
contents of the display will scroll. Tables can be constructed to display and 
scroll over large databases. 
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Selection of Text or Cells 


Many commands require the user to select text or cells as operands. For 
example, the user selects some text within a cell to be erased, or a range of 
cells to be duplicated. 


As the user presses arrow keys, CODE-B, CODE-C, or CODE-R, the selection is 
highlighted by the Common Code. The user can change the selection as much as 
desired before pressing CODE-RETURN to confirm the selected text or ceils. 


The selection area is always a rectangle no matter how the user moves the 
outline or cursor. The first selected cell and the current cell (i.e., with 
the outline) form two corners of this rectangle. The first selected cell is 
known as the “anchor,” because the selection appears to be anchored to it. 


CODE-B allows the user to restart the selection. When the selection is 


restarted, the original anchor is discarded and the outlined cell becomes the 
new anchar. 
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CHAPTER 3: DATA TYPES 


This chapter defines the basic data types used in this manual. Every package, 
such as the tahle routines, has other data types that are defined specifically 
for it. The unique data types are defined in the same chapter where their 
corresponding routines are described. 

STANDARD DATA TYPES 


Table 3-1 lists the basic data types found in the Common Code. 


Data Types 3-1 


Type 


Boolean 


Integer 


LongInt 


Word 


Byte 


Char 


Real 


LongReal 


Description 


An ordinal type with two values, 
False (0) and True (1). 


A simple ordinal type of two bytes 
in the range -32768 to 32767. 


A siaple ordinal type of four bytes 
in the range of -2,147,483,647 to 
2,147,483,646. 


A simple ordinal type of two bytes 
in the range of 0 to 45535, 


An enumerated ordinal of the range 
0..255. Not to be confused with the 
Bytes type, described below. 


A simple ordinal defined on the ASCIT 
character set. 


A simple type defining single-precision 
floating point numbers with 24 bits of 
precision. 

A simple type defining floating-point 
numbers with 53 bits of precision. 


Table 3-1. Standard Data Types 
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THE BYTES TYPE 


A special data type has been defined to override PASCAL’s rigorous 
type-checking. It is the Bytes type. Note that it is NOT the Byte (singular) 
type, which is defined to be 0.,255, The Bytes type is not a part of standard 
PASCAL. The PASCAL-86 User‘s Guide describes it in more detail. 


The Bytes type allows you to pass any type of data to a function or procedure. 
The passed data must match what the procedure expects to receive, of course. 


The Bytes type is used to implement literals, such as literal character 
strings. For example, 


NewStringLit(VAR lits Bytes): StringPtr; 
accepts these literal inputs: 


VAR stringArray: ARRAY [1..80} OF Char; 
aString: StringPtr; (see Chapter 4) 


x t= NewStringLlit(‘abcdef'); 
x r= NewStringLit(stringArray); 
x = NewStringlit (aString*.chars[1]); 


When passing a parameter of type Bytes, the procedure actually passes a 

pointer to the code itself. Hence, all Bytes parameters must be passed by 
reference rather than by name. The Bytes identifier can appear only in an 
external module’s PUBLIC section: see the PASCAL manual for more details. 


COMMON CODE DATA TYPES 


This is a summary of the data types in the Common Code. The data types for 
each package are defined at the beginning of the appropriate chapter. 


Common Properties 


AuthorType 

HeadingType 
ForafeedType 
ColumnType 

TypeSize 
PrintOptionsRecord 
CommonPropertiesRecord 
General Record 
GeneralRecordPointer 
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Data Driven Foras 


SomeArrayOfBytes 
Pointer ToSomebytes 
DatakindType 
DataFormMadeType 
DataKkindAliasType 
DataRowType 
DataFormType 
DataMenuType 


Fields 


Alignment 
Fieldkind 
FieldDescriptor 
FieldPtr 
FieldEditResult 
SetType 
CursorDescriptor 


File Form 


FFModeType 
FFExchangeMode 
FFExchangeResult 
FFSaveResuit 
DefaultType 


Menus and Foras(Not Data Driven? 
MenuForaDescriptor 
MenuFormPtr 
ChoiceRequest 
UpdateKind 

Messages and Prompts 


MessageStatus 
MessagePtr 


Strings 
Literal 


StringDescriptor 
StringPtr 
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Tables 


® GolArray 


ColPtr 

ScreenArray 
ScreenPtr 

Cellid 
SelectionRangekind 
TableSelection 
CellTable 
TextCursor 
CellTablePtr 
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CHAPTER 41 COMMON PROPERTIES AND OPTIONG 


Much of the power of the GRiD Management Tools application programs derives 
from the ability of all the applications to operate on the same set of data 
files, Thus, a database file created in GRiDFile can be taken into the 
GRiDWrite application for use in a text file or taken into GRiDPlot to obtain 
a graphic display of data. The files can be freely exchanged between 
applications without reformatting the data. 


This flexibility and power are achieved by ensuring that the data in all] files 
is in a well-defined format regardless of which application created or most 
recently changed the file. The scheme used also allows applications to 
include additional (non-data) information in files to describe special 
attributes, or properties, of the file. 


INTERCHANGE FILES 


Files that conform to the format used by GRiD application programs are called 
“interchange files". These files can contain three different kinds of 
records; data records, common properties records, and application properties 
records, Data records contain the actual text and numerical values 
comprising the "meat" of the file. Common properties records describe such 
things as how data in the file is to displayed or printed by all applications 
Programs. Application properties records have special meaning only within a 
particular application. There are three rules that must be observed with 
records in interchange files: 


4. Data records can contain only printable characters, carriage return 
characters, line feed characters, and tab characters, 

2. Properties records (both common and application) must begin with a 
non-printable character (FF, FE, and FD hexadecimal are currently 
assigned special significance). 

3. Common properties records (if any) must be the first records in an 
interchange file. (Application properties and data records can occur 
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in any order after the common properties records.) 


DATA RECORDS 


Interchange file data records are stored in a tabular format: 

peach record consists of a line of printable characters (text or numbers) 
terminated by a carriage-return line-feed pair and corresponds to one row of 
data in a table, Tab characters can also be intermixed with the printable 
characters in a record. In cell-based data files, such as worksheets, 
database, and graph files, a Tab character is used separate adjacent cells 
within a row. 


Thus, the data records in a file consist only of printable characters, 
carriage return characters (OD hex), line feed characters (OA hex), and tab 
characters (09 hex). The following illustration shows the organization of a 
data record: 


line Feed 
carriage return —3 


[ [5+ [1 foo [se] 5] 03 os [22] 2 | co} on | 
aE ie ae 
tab 


Oa heh: 


space 


S 


Figure 4-1. Interchange File Data Record Format 


This illustration shows the contents of the record in hexadecimal 
representation and the ASCII equivalent of the record’s contents below the 
figure. Each byte in the record contains a printable ASCII character or the 
tab character, and the carriage-return line-feed pair mark the end of the data 
record. 


PROPERTIES AND OPTIONS 


In order to tightly integrate GRiD applications, some attributes which define 
the display and printing of data files are stored within the files. These 
attributes ensure that a visual appearance of a file when it is displayed or 
printed will be the same regardless of which application is currently 
operating on the file. 


These attributes can be set in various ways within an application. The 
Options (CODE-0) command is used to set display attributes that apply 
throughout an entire file, and the Properties (CODE-P} command is used ta set 
attributes that apply only to a column, row, or range of cells. Attributes 
that apply when a file is being printed are set via an item ("Set Print 
Options") selected from the Print menu of the Transfer command. 
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COMMON PROPERTIES RECORDS 


When an application reads in a data file, it can examine the first byte of the 
file to determine whether the file contains any common properties records. 

(lf there are any common properties records, they must be the first records in 
the file, preceding any data records and application properties records.) If 
the first record is a common properties record, the first byte read will 
contain the “common properties flag" byte of FE (hexadecimal), 


The format of common properties records can be illustrated as follows: 


Connon Properties 
Flag Byte 


Type oF property 
being defined in record 


properties 
Seas 


A word indicating nunber oF butes 
CFollouing “length"> in the record. 


Figure 4-2. Common Properties Record Format 


The two bytes (word) following the common properties flag byte (FE hex) define 
the number of bytes in the record (excluding the flag byte and the 2-byte 
length indicator). The common properties record identifier (cprID) byte 
(after the length word) defines which of the common properties this record 
describes. The cprID bytes currently defined are as follows: 


cpriD Byte Property 

Hex ASCII 

61 a Author (application) of this file 
43 € Coluan field properties 
64 d Standard field properties 
6é f Cell field properties 

68 h Text header properties 
6c t Row height properties 

46D ci) Print option properties 
6E i) Font properties 

72 Fi Row field properties 

74 t Table size properties 

77 # Coluan width properties 


The cprID byte tells you which of the common properties recognized by GRiD 
applications is described in a record. If there are any common properties 
records in an interchange tile, the first record of the #ile must contain the 
“author of this file” record. 
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The properties listed above can be grouped into three categories: @ 


i. The Author ID property 
2. Font properties and Print Options 

o Font properties 

do Print options 

o Text header properties 
3. Field Characteristics 

o Standard field properties 
Column fieid and width properties 
Row field and height properties 
Cell field properties 
Table size properties 


oa00 


AUTHOR RECORD 


This record MUST appear first in an interchange file if the file contains ANY 
common properties records. It tells you which application first wrote this 
file. The format for the Author record is as follows: 


Connon Properties cprID 
Flag Byte authorID = G1 hex, ASCII “a" 


Data 
it- File 


Version 
T. Product 8 
ae at Code 


Figure 4-3. Author Record Format 


As shown in this illustration, this record has four bytes following the length 
word. NOTE: Words are always stored with the low-order byte first. Thus, in 
the length word shown above, a length of four appears as 0400 (hex). The 
first byte after the length word indicates that the record is an authorID 
record, the next two bytes contain a product code identifying the application 
that created the data file, and the last byte is the data version (or 
compatibility level) of the data file. The product codes currently defined 
for GRiDd applications are as follows: 
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Application Product Code 
Decimal Hex 


GRiDFile 2110! 5260 
GRiDPlan 211il 5277 
GRiDPlot 2112 © S28L 
GRiDWrite 21131 5288 
GRiDTera 24i41 5295 
GRiD3101 24151 9 S29F 
GRiDVTI00 21191 52C7 


The data version byte at the end of the authorID record defines the 
compatibility level of the data file. For example, database files created by 
2.0 and 1.0 versions of GRiDFile would have this byte set to O01 (hex) while 
files created by the 3.0 version of GRiDFile have this byte set to 02. This 
indicates that database files created with older versions of GRiDFile are 
incompatible with 3.0 GRiDFile. 


FONT PROPERTIES AND PRINT OPTIONS RECORDS 


These three records define the font to use when displaying a data file, the 
options ta use when printing a data file, and the text header (if any) to use 
when printing. 


Font Record 


GRID application programs let the user select from a number of available fonts 
(or typefaces) to obtain the screen display of data most suitable for their 
needs or personal preference. (See Chapter 11 for a discussion of fants.) 
The common properties Font record defines which font is to be used when 
displaying a data file. The format of the record is as follows: 


Connon Properties 
Flag Byte 


cprld 
FontID = GE hex, ASCII “n" 


tunber of 
bytes Following 
“length” 


Figure 4-4. Font Record Format 
The text string that is the name (title) of the current font follows the 


fontID byte. This is just the font name, for example "System-Wide" or "GRiD 
64”, not the pathname of the file. 
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Print Options Record 


The Print Options record defines the way in which a file will be printed. The 
information in this record is originally obtained from a Print Options form 

which GRiD applications can display after a user has selected "Print" from the 
Transfer menu. The items on the Print Options form correspond to the entries 

in the Print Options record whose format is as follows: 


Connon Properties 1D 
Flag But cpr. 
pai SY J orintptioneto = 6D hex. ASCIT "a" 


vanoth = it ] 
Left 
Margins Right 


Tor 
Botton 


Forn Feeds 
Colunn Headings 
Text Headings 
Colunn Spacing 
Row Headings 
Letter Size 


Figure 4-5. Print Options Record Format @ 


The left and right margin bytes indicate the character positions where the 
first and last characters on each line are to be printed, The top and bottom 
margin bytes specify the first and last character lines on a page where data 
is to be printed. (The first possible Line number is 1, and the first 
possible character position is 1.) 


The Form Feeds byte specifies when form feeds are to be sent to the printer as 
follows: 


no fora feeds 

form feeds before printing begins 
form feeds after printing is finished 
form feeds before and after printing 


Pane 


The column headings byte and the text headings byte specity when the column 
and text headings from a data file are to be printed as follows: 


print no headings 

print headings on first page only 

print headings on every page except first page 
print headings on every page 


Pune 


The contents of the column headings are generated within each application as 
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appropriate and would be indicated in the data file by “private", or 
application-dependent, properties records (discussed later in this chapter}. 
The Text Heading data is defined in the common properties record described in 
the next paragraph. 


Text Heading Record 


Text headings are independent of the application and they simply consist of a 
text string that can be printed (as specified by the column headings byte} 
centered at the top of pages. The format for the Text Heading properties 
record is as follows: 


Connon Properties 
Flag Byte 


[re Tien [oe | 
+ 


number oF 
bytes Following 
"length" 


cprID 
textHeadingID = 68 hex, ASCII "h" 


a 


Figure 4-4. Text Heading Record Format 


FIELD CHARACTERISTICS RECORDS 


These common properties records define the alignment and format of data 
displayed in columns, rows and cells, the width of columns, the height of 
rows, and the size of a table. 


A single cell can have its properties defined in ane of four ways: 


o By a cell field properties record (one or more cells selected after 
CODE-P) 

o By a column field properties record (an entire column is selected 
(CODE-C after CODE-P ) 

o By a row field properties record (an entire row is selected (CODE-R 
after CGDE-P } 

o By a standard field properties record (the Options command -- COBE-O) 


Notice that a cell does not have to have its properties explicitly defined. 
Initially, a data file has all of its field (cell) characteristics defined by 
the standard field properties record; no additional field properties records 
are required until a user sets properties in an file (using the CODE-P 
command). At that point, you must create a properties record for the fields 
that were changed to be different than the standard settings. Depending on 
what fields the user selected, a cell, column, or row properties record will 
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be required. 


The approach used in defining properties @inimizes the total number of field 
properties records that are required to fully describe the characteristics af 
a data file and thus keeps the file as small as possible. Obviously, it would 
be inefficient to define cell properties individually if all of the cells in a 
row or column have the same properties. Similarly, there is no need to define 
the properties of a column or row if they are they same as the standard 
properties, 


To determine the properties of a cell, GRiD applications first look to see if 
the properties are defined in a cell field properties record. If not, then 
the column, row, and standard field records (in that order) are examined. The 
first of these records that contain a definition for the cell in question is 
the one that takes precedence. 


Whenever a user sets properties for cells, columns, or rows, the application 
may have to alter previously set properties if they differ from the new ones. 
Therefore, existing properties records may have ta be deleted or changed and 
New ones created. Since the search sequence defined for determining cell 
properties looks first to the cell, then the column, and thirdly to row, an 
application must examine field property records in that order to check for 
possible conflicts between new properties settings and previous ones. 


For example, if you are changing the properties of a row, you would follow 
these steps: 


1, Check for a cell properties record for the row being defined. Since 
cell properties records are defined on a per-row basis, and since the 
entire row is being defined, a cell properties reocrd for this row can 
be discarded. 

2, Check for existing column properties records. If one or more column 
properties records conflict with the new row properties, then cell 
properties records must be defined for the intersections of the row 
and any conflicting columns. 

3. Check existing row properties. If a field record already exists for 
this row, update it accordingly. If does not exist, create a new row 
field properties record. 


NOTE: A special value of 255 decimal {FF hex) can be used in cell, coluan, and 
row field properties records to indicate that the "default" properties should 
be used. Default, in this context, means "do not use this properties byte; 
instead, look to the next level of field properties records for the 
Properties." Thus, if you encountered the default byte (255) in a cell field 
properties record, you would then look to the column field record for 
properties. 


4-B Common Code Reference 


6 


S 


Standard Field Record 


The Standard Field properties record defines the standard settings for column 
width, format (decimal, integer, etc.), and alignment (left, center, right). 
These settings are defined by the user in GRiD applications with the Options 
(CODE-G) command. The format for the Standard Field properties record is as 
follows: 


cerit 
standardField1U = 64 has, ASCII "d" 


“application 
Field props 


Connon Properties 
Flag Byte 


unber of Format~alignmnt 
butes Following column width 
“length" number of baybes 


per property 


Figure 4-7. Standard Field Record Format 


The byte following the standardFieldID, indicates the number of bytes that 
will be used to define each field property. Currently, most GRiD-developed 
applications use only a single byte to define the field properties of format 
and alignment. The bytes/property indicator, however, provides for using 
multiple bytes in the future to allow larger values or define additional field 
properties, 


NOTE: The bytes/properties value specified here applies not just for the 
standard field record, but also to the row field, column field, and cell 
field property records which will be described later in this chapter. 


The next byte defines the standard width for columns in cell-based 
applications. (6RiD-developed applications currently use a standard width of 
8 characters for coluans.) 


The format/alignment byte defines the standard arithmetic format (decimal, 
integer, etc) that will be used and the standard alignment (left, centered, 
right) that will be used for displaying data in cells. (GRiD-developed 
applications currently use a standard format of integer and a standard 
alignment of right-justified.) The 5 most-significant bits of this byte 
specify the format and the three least-significant bits specify the alignment, 
The contents and interpretation of this byte can be illustrated as follows: 
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Bit > 2 6 S 4 a) 2 1 0 | 


arithmetic Format (0 - 313 alignment (0 - 7) 


Pea ean aie rae ae | eee aie i aS ares 
Decinal Fornst Specified Decinal Alignnent Specified 
[i] Integer a Left aligned 
1-15 # of decinal places L Center aligned 
30 Scientific notation 2 Right aligned 


Figure 4-8. Format/Aignment Byte of Field Records 


Column width and format/alignment are the only standard properties currently 
defined across all cell-based GRiD applications. However, each application 
Can append additional standard properties bytes following the format/alignment 
byte. Thus, each application can establish any application-specific standard 
properties (Options) it might need. For example, GRiDPlan has options defining 
such things as evaluation order (row versus column), and whether or not to 
display a grid as a background for the worksheet. 


Coluan Field Record a 


The Column Field properties record defines the settings for arithmetic format 
(decimal, integer, etc.), and alignment (left, center, right). This record 
overrides the settings of the Standard Field properties record and would be 
created as a result of the user setting coluan properties using the CODE-P 
command, The format for the Coluan Field property record is as follows: 


Connon Properties 


cerID 
colunnFieldID = 63 hax, ASCII "c* 
ist non-standard colunn # 


nunber oF Format and alignment 
bytes Following Por each column Fron ist @ 
“length” through last non-standard column 


Figure 4-9. Column Field Record Format 
The colFieldPropsID byte (43 hex) follows the common property flag and the 


length word. The next word indicates the first column in the file that is of a 
non-standard format or alignment. (NOTE: although a {6-bit word is provided 


4-10 Common Code Reference 


@ 


to define the column number, no GRid-developed applications currently allow 
more than 255 columns.) The subsequent bytes define the format and alignment 
of each of the succeeding columns. You must define the column format and 
alignment (even if they happen to be standard) of all columns until the last 
non-standard column has been defined. For example, if coluans 2, 5, 7, and 7 
(in a table that is 15 columns wide) are non-standard, the ColumnFleld record 
must define the format/alignment of columns 2 through 9. Columns 1 and 10 - 
15 will assume the standard format/alignment, but you must explicity define 
the standard format/alignment for columns 3, 6, and 8 in the Coluan Field 
record. You can specify standard format for a column in this record with a 
value of 31 (decimal) and standard alignment for a column in this record with 
a value of 6 (decimal). The following illustration shows the organization and 
interpretation of the format/alignment bytes in the Coluan Field record. 


Bit #7 6 5 kj 3 2 i 0 


+ phere how at t t 
arithnetic Format ¢O0 - 313 alignment €0 - 72 


F aaeishraslas Mahal ira ainda Y Fe eee uae 
Qecinal Fornat Specified Decinal Ailignnent Specified 
fi] Intager 6 Left sligned 
1-15 # of decinal places af Center aligned 
30 ScientiFic notation 2 Right aligned 
3 Use Standard Fornat 6 Standard alisnnent 


285 = Ignore this byte. Use default 
record For Fornat & alignnent. 


Figure 4-10. Coluan Field Record Format/Alignment Byte 


This is the same as was shown earlier for the Standard Field properties record 
with the addition of the "Standard" and "Default" definitions. (Those 
definitions obviously had no meaning with the Standard Field properties record 
since that record itself defines the “standard” and it is also the last place 
you look for "default" definitions.) 


Row Field Record 


The Row Field properties record defines the settings for arithmetic format 
(decimal, integer, etc.), and alignment (left, center, right). This record 
overrides the settings of the Standard Field properties record and would be 
created a5 a result of the user setting row properties using the CODE-P 
command. The format for the Row Field property record is as follows: 
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cprld 


Connon Properties 
rouFieldIU = 72 hex, ASCII "r" a 


Flag Byte 


ist non-standard rou # 


one byte per row 
4 n 


+ 
nunber of Format and alignnant 

bytes Pollowing For each row Fron ist row # 
“Jenath" through last non-standard row 


Figure 4-11. Row Field Record Format 


As you can see, this record is nearly identical to the Column Field record 
described earlier. The only difference is the cpriD byte value. 


Coluan Width Record 


The standard column width for cell-based applications is specified by the 
Standard Field Record (described earlier). If one or more columns in a data 
file are set {via the Properties command in an application) to be different 
than the standard width, you must write a ColumnWidth record into the data 
file to define the non-standard columns, The format for the Column Width 
common property record is as follows: 


Connon Properties cprlf a 
Flag Byte colunnWidthIG = 77 hex, ASCII "uY 
ist non-stal colunn # 
[Fe ] senntn [2 [Jove hte ror column | 
ee es 

number of Colunn uidth Cin characters) 

bytes Following Por each colunn Fron ist # 
"length" up to the next standard colunn 


Figure 4-12. Column Width Record Format 


The colWidthID byte (77 hex) follows the familiar common property flag byte 
and the length word. The next word indicates the first column in the file 
that is of a non-standard width. (NOTE: although a 16-bit word is provided to 
define the column number, no GRiD-developed applications currently allow more 
than 255 columns.) The subsequent bytes define the width lin characters) of 
each of the succeeding columns. You must define the column widths (even if 
they happen to be standard width) of all columns until the last non-standard 
column has been defined. For example, if columns 2, 5, 7, and 9 (in a table 
that is 15 columns wide) are-non-standard, the ColumnWidth record must define 
the widths of columns 2 through 9. Columns 1 and 10 - 15 will assume the 
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standard column width, but you must explicity define the standard column width 
for columns 3, 4, and 8 in the ColumnWidth record. You can specify standard 
width for a column in this record with a byte of FF hex (255 decimal). 


RowHeight Record 


The standard row height for cell-based applications is one character line. 
This is also the only value used in GRiD application programs and none of them 
currently make any provision for setting a row height other than one character 
line high. 


However, to provide for possible future enhancements, a common properties 
record is defined for row height. The format for this record is as follows: 


cprlil 
rouHeightID = 6C hex, ASCII "1" 
ist non-standard rou # 


[reese Toe [| 
+ 


Connon Properties 
Flsg Byte 


one byte per row 


funber oF Row height Cin char lines? 
bytes following For each row Fron ist rou # 
“Jength" through last non-standard rou 


Figure 4-13. Row Height Record Format 


As you can see, this record is almost identical to the ColumnWidth record; 
only the rowHeightID byte (4C hex) is different. 


Cell Field Record 


The Cell Field properties record defines the settings for arithmetic format 
(decimal, integer, etc.), and alignment (left, center, right) within 
individual cells. This record overrides the settings of the column or row 
properties records and would be created as a result of the user setting 
Properties using the CODE-P command for a cell or range of cells. The format 
for the Cell Field property record is shown in the following illustration: 
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Connon Properties 
Flag Byte 


cpr]D 
cellFieldID = 66 hes, ASCII "F" 


‘ona byte per } 


| Fe | length | «6 | ist CH [row # | colunn 
Ee ay ane 
nunber of it. is 
bytes Pollouing Rou # gor wach cell Fron 
“Length” being 4st CH through last 
def ined 


Figure 4-14. 


non-standard cell 


Cell Field Record Format 


The cellfieldPropsiD byte (46 hex) follows the common property flag and the 
length word. The next word indicates the first column in the row that is of a 


non-standard format or alignment. 


{NOTE: although 16-bit words are provided to define the column number and 
the row number, no GRiD-developed applications currently allow sore than 


255 columns or rows.) 


After specifying the column number, the next word specifies the row where 


format/alignment is being defined. 


The subsequent bytes define the format and 
alignment of each of the succeeding cells within that row. 


You aust define 


the cell format and alignment (even if they happen to be standard) of all 


cells in that row until the last non-standard cell has been defined. 


For 


example, if columns 2, 5, 7, and 9 Cin a table that is 15 columns wide) in row 
3 are non-standard, the CellFleld record oust define the format/alignment of 


cells in columns 2 through ? in row 3. 


Cells in columns 1 and 10 - 15 will 


assume the standard format/alignment, but you must explicity define the 
standard format/alignment for cells in columns 3, 4, and 8 in this Cell Field 


record. 


You can specify standard format in this record with a value of 31 


(decimal) and standard alignment for a column in tnis record with a value of 6 


(decimal). 
the format/alignment bytes. 


Note that you mus* define a Cell Field record on a per-row basis. 


See the discussion of the Column Field record for a descripton of 


Each record 


indicates the row number where non-standard properties exist and also the 
first column within the row where non-standard properties begin. 


TableSize Record 


This common properties record is not currently used by any GRID applications. 
Jt is intended to let you quickly discover the size of an entire table in a 


data file. 


However, Since most GRiD-developed applications provide an Append 


command, the size of a data file and, thus its table, can be changed without 


ever bringing that file into memory. 
still defined and may be of future use. 
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Nonetheless, the Table Size record is 


Its format is as follows: 


Connon Properties 
Flag Byte 


cer! 
tableSizel® = 74 haa. ASCIT "4" 


ea 
Lenath = 5 


Figure 4-15. Table Size Record Format 


APPLICATION PROPERTIES RECORDS 


Application properties records can appear anywhere within a data file (except 
that they cannot appear until after any common properties records). They have 
predefined beginning identifiers but the actual contents of the records can be 
in any format and are interpreted within the context of that application. 


The format for the type of application properties record currently used in 
most GRiD applications is as follows: 


Application Properties 
Flag Byte, 


Application Properties Record 
1D Cuser-def ined> 


[Fo | tengtn [2 | --application properties .... 


A word indicating nunber of bytes 
CFolloving "length"? in the recerd 


Figure 4-16, Application Properties Record Format (Binary) 


These records begin with FD (hexadecimal) and identify an application 
properties record that consists of binary data. The word following the 
application properties flag byte defines the length of the record -- that is, 
the number of bytes following the "length” word. 


Application properties records that begin with a byte of FF (hexadecimal) are 
expected to contain ASCII (textual) data and are terminated with a 
carriage-return line-feed pair (just like a data record). The format for this 
type of record can be illustrated as follows: 
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Application Properties Line Feed 
Flag Bute Carriage Retuen =r 


[FF | application properties “ASCII 


Figure 4-17. Application Properties Record Format (ASCII) 


This type of properties record is currently used only in GRiDPian to allow 
ASCII formulae describing cell definitions. Other GRiD applications use the 
binary format with its "length® word to store application properties records. 


PROPERTIES RECORDS COMMON CODE ROUTINES 

The Common Code package provides several routines to simplify the handling of 

properties records, The available calls and their purpose are as follows: 

Comaon Code Call Purpose 

Author OfThisFile Returns the author product code word and version 
byte from the first common properties record in a 


data file. You can then decide whether you need to 
look at application properties records in the file. 


SkipProperties Skips over all the common properties records in a 
data file. 
GetNextRecord Returns a pointer to the next record in a data file 


and also returns the length of the record. You can 
also specify that the call automatically skips over 
all application properties records in the file if 
you are not “author of this file". 

FinalizePropertiesLength Calculates the current length of all the common 
properties records in a data file and records that 
value in the file header for the file when it is 
written to a device. This value lets the 
SkipProperties call skip over the common properties 
when the file is subsequently read. 


For a complete description of these calis, refer to Chapter 12. 
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CHAPTER Si BTRINGS 


The Common Code string routines add ASCII] character string manipulation to 
PASCAL. The strings are dynamic structures that can be allocated as needed 
while a program executes. They avoid PASECAL‘s rigorous type-checking, so 
their length does not need to be defined until they are referenced in a 
Pprogran. 


DATA STRUCTURES 


# TYPE StringDescriptor = 
RECORD 
Ten,max: Word; 
dummy: Byte; 
chars: ARRAY [!..65535] OF Char; 
END; 


StringDescriptors have these elements: 


Ten The current length of the string. It may vary from 0 to max. Do NOT 
allow it to exceed string.max, 


max The maximum length of the string in characters, NEVER MODIFY MAX 
because the memory allocation routines refer to it when they create 
or dispose of the string. Also, do NOT refer to a character position 
beyond the max, because your doing so may destroy the memory space of 
other variables. 


dummy A dummy variable that was included so that PASCAL strings will be 
compatible with PL/M strings. The dumay enables the PL/M character 
array to be declared beginning with a 0, because PL/M arrays must 
begin at 0. Then, both PASCAL and PL/M can refer to all strings by 
beginning with string. chars(1]. 


Strings 5-1 


chars An array of characters, which is the actual string itself. Even 
though the string array has been declared 65535 characters long, you 
would never actually allocate a string this long. This "dummy 
Yength” enables the string package to allocate strings of different @ 
length during program execution. You can pass these strings as VAR “ 
parameters because they are not PACKED. 


Note: These string structures must not be allocated with PASCAL allocation 
routines. You must create and dispose of them with the special procedures 
(NewString and NewStringLit) described below. 


* TYPE StringPtr = “StringDescriptor; 


The StringPtr is the most common device for actually referring to a string or 
passing it as a parameter of a procedure, In fact, this pointer structure is 
what permits the string package to create and dispose of strings dynamically. 
Many common code and string routines require StringPtrs as their arguments. 


* TYPE Comparison = (equal, less, greater); 


A value of type Coaparison will be returned from the string comparison 
routines (EqualStrings and CompareStrings). A result of less or greater means 
that the ASCII values of some characters in one string are numerically less or 
greater than those in another. 


THE STRING ROUTINES G 


Coamon Code provides routines to allocate and deallocate strings, compare and 
modify strings, convert strings, and operate on substrings. In this chapter 
we will provide an overview of the routines available and give brief examples 
of their use. Complete descriptions of the individual routines are provided 
in the alphabetically ordered reference chapter -- Chapter 12. 


Allocating and Deallocating Strings 


Two Common Code functions are provided to allocate strings and a third is used 
to deallocate strings. 


NewString Allocates memory for a new string of a specified length and 
returns a string pointer to that area in memory. 

NewStringLit Takes a literal string, allocates memory for it, and returns a 
string pointer. The maximum length (max) and current length 
(en) of the new string is the length of the literal 
characters. 

FreeString Given the StringPtr to a string, FreeString will release the 
memory that the string occupied and return that memory to the 
PASCAL heap. 
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CAUTION: GNLY NewString and NewStringLit WILL PROPERLY ALLOCATE SPACE FOR 
STRINGS. NEVER call New(StringPtr) because New will allocate all 65535 bytes 
according to the deciaration of String*.chars[i..655352 above, 


When deciaring your own static variables to deal with strings, you must 
declare them to be StringPtrs, NOT Strings. If you declare a static variable 
as type String, the compiler will try to allocate 65535 bytes for 
String*.chars€1..65535] according to the declaration of the String record. 
You should declare the variable to be of type StringPtr and then assign it 
with the value resulting trom a call to NewString or NewStringLit. 


Note: you must NEVER modify String*.max, because FreeString uses that number 
to determine how much memory to release to the heap. Other data values may be 
incorrectly released if String*.max is changed from its original value. 


Comparing Strings 
Two functions are provided to compare strings: 


EqualStrings Compares two strings character by character and returns True if 
they have the same characters and the same number of 
characters, 

CompareStrings Compares the ASCII values of two strings character by 
Character, from left to right. Thus the greater string will be 
the one containing the first character with a higher ASCII 
value. If two strings match up exactly except that one string 
has additional characters, then the string with the extra 
characters will be the greater one. 


Modifying Strings 


Twelve different routines are provided by Common Code to give you great 
flexibility in modifying strings and manipulating: 


CopyString Copies the value of the source string to the dest string. 
Both source and destination aust be allocated already. 

CopyOfString Creates a new string and copies the value of str to it. 

AppendString Concatenates a source string to the tail of a destination 
string. The source string remains unchanged. 

AppendChar Appends a single character to the tail of a destination 
string. 

AppendAnyChar Appends a single character to the tail of the string. It 


disposes of the original str and sets str to the newly 
created string. 


Concat Creates a new string containing stri and str2 concatenated 
together, 
ConcatStrings Creates a new string containing str1 and str2 concatenated 


together and dispases of stri and str2 after creating the 
new string. 

ConcatLits Creates a new string with the literals lit! and lit? 
concatenated together to let you concatenate string 
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constants, 

DeleteFromString Deletes characters from a string and then joins the 
remaining characters together to close the gap. 

InsertinString Inserts a string into another string. The existing @ 
characters of str are moved aside to make room for the - 
insertion. 

InsertCharInString Inserts a single character into a string beginning at a 
specified character position. 

SubStringLit Returns the Nth item (specified by count) from a literal 
that contains text items separated by delimiter characters. 


Converting String Types 


Five routines are provided to perform real number conversion, integer 
conversion, and convert lower case characters to uppercase. 


UpperCase Converts any lowercase alphabetic characters in the string 
to uppercase. It does not shift up numerals, punctuation, 
or specia! characters. 

IntegerToString Converts an integer between -32748 and 32747 inclusive into 
a string, then returns a stringPtr to the string value. 

StringToInteger Converts a string value into an integer. The string aust 
represent an integer between -32768 and 52767 inclusive for 
the conversion to succeed. The variable “converted" 
indicates whether the conversion was successful or not. 

RealToString Converts a fifteen digit real number into a string variable. 
(The 8087 numeric processor uses fifteen and a half digits 
of precision; this routine returns fifteen digits, rounding a 
off the half digit as necessary.} 

StringToReal Converts a string value into a real number. The variable 
“converted” indicates whether the conversion was successful 
or not. It will convert up to the first fifteen digits, 
and drop any extra digits without causing an error. If the 
conversion fails (from incorrect input, for example) the 
routine returns 0. 


Note that the two real number routines produce real numbers of fifteen and a 
half digits. They cannot accomodate exponential notation, such as 6. 03E+23. 
For details, see the Intel 8087 Floating Point Processor Manual or the Pascal 
Manual. 


Miscellaneous String Routines 


Five routines are provided to simplify handling of various other strings used 
throughout the system. 


TimeToString Converts tise and date information from the 05 to a string 
for easy use in an application. 
SubProperty Picks a name out of a string made up of names and special 


characters. The special characters are delimiters in the 
GRiD-OS file system. 


O 
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SetPrefix 
GetVersionString 


TranslateHeading 


Used by the application to set the prefix subject. 

Returns a string containing a three numeral version number 
of a piece of software. Each process (application) can have 
a version number. 

Translates the input into a centered output string for 
printing on an Epson printer. Special symbols are 
translated in the upper or lower case 
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CHAPTER 6. COMMANDS, MESSAGES, AND PROMPTS 


These Common Code routines simplify implementation of several commands that 
are used in all GRiD-developed applications and provide a standard, 
easy-to-use mechanism for displaying messages and prompts. 


Conaands 


The four command-related routines provided by Common Code are listed in the 
table below. Two items that are standard on the Transfer menu supported in 
all application GRiD applications are “Erase a file" and "Show file 
characteristics" The first two calls listed in the table (CmdErase and 
CmdProperties) let applications share the code needed for these activities. 
Similarly, CmdMediaUsage and GetVersionString are supplied ty Common Code 
since CODE-U and CODE-? are supported by all GRiD applications. 


Routine Description 

CmdErase Erases a file and displays appropriate prompts and messag 
Used to implement “Erase a file” from the Transfer menu. 

CndProperties Displays the properties of a specified file, Used to 
implement “Show file characteristics" from the Transfer 
menu, 

CadMediaUsage Displays memory and media usage. Used to implement the 


CODE-U command. 
GetVersionString Returns a pointer to the version number string of the 


specified process. Used to display an application's version 


information as part of the CODE-? screen and when the 
application is first loaded. 
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MESSAGES AND PROMPTS 


window (full window width). The text is highlighted (inverse video) and its 
default position (which is the one typcally used by GRiD applications) is the 
bottom of the window. When a message or prompt is erased, it is the 
responsibility of-the application to update the necessary rectangle. In GRiD 
applications, messages and prompts are handled in slightly different ways . 
The conventions used in SRiD applications are as follows: 


Messages and prompts are text fields that can be displayed anywhere in the OC 


Messages -~ A message should be displayed only until the next keystroke 
by the user of the application. For example, the user presses CODE-U to 
see media usage, the usage message appears, and remains on the screen 
until the user presses another character. The message should always be 
cleared BEFORE a character is processed. 


Prompts -- A prompt should be displayed only while an application is in 
command mode or responding to a MsgExit routine. The prompt persists 
until one of the following criteria is satisfied: 

1. The user satisfies the condition of the prompt and presses 

CODE-RETURN. 

2. The user presses ESC to escape the condition of the prompt. 

3. The user presses another CODE key to preempt the current command. 
Prompts should be cleared after a character is processed unless the 
application is remaining in command mode. For example, if the users 
presses CODE-D to duplicate, the prompt “Duplicate: Make a selection and 
confirm" is displayed. This prompt should remain displayed while the 
user presses arrow keys to make a selection. The prompt should be 
cleared only when the user presses CODE-RETURN to confire the command or @ 
when the user presses ESC or another CODE~key command to pre-eapt the 
current command, 


Note that these conventions are not enforced by the message and prompt 
routines; rather they are conventions observed by GRID applications and which 
should be adhered to by other applications for the sake of consistency. 


Data Structures 


An application and the Common Code communicate message/prompt information by 
passing a pointer to a dynamic data structure of type MessageStatus. This 
variable must be declared in the application and initialized (dynamically 
allocated) by a call to FUNCTION MsgInit. (See MsgInit) The organization of 
the MessageStatus record is as follows: 


TYPE MessageStatus = 
RECORD 
messageShowing: Boolean; 
stackSize : Byte; 
field: FieldPtr; 


rect: Rectangle; {area to be updated} 
anythingShowing : Boolean; 
END} 
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MessagePtr = “MessageStatus; 


messageShowing A boolean that indicates if a message is currently 
displayed. If a prompt is showing, or if no message is 
-showing, it is false. This field is NOT altered by the 


application. It is initialized by MsgInit and updated by 


the various message calls. 


stackSize Indicates the number of messages/prompts currently showing. 
This is NOT altered by the application. It is initialized 


by MsgInit and updated by the various message calls. 


field Pointer to the field descriptor record containing the text 


and location of the message. 
rect The rectangle that the application should update if the 


boolean result of one of the message FUNCTION calls is true. 
This value is initialized by MsgInit, updated by the various 


message calls, and read by the applications. it is not 
altered by the applications. 


anythingShowing Boolean field that is not used in the current version of the 


Common Code message module. 


The organization of the field descriptor record pointed to by the field 
parameter is as follows: 


FieldDescriptor = RECORD 
box: Rectangle; 
tex StringPtr3 
kind: FieldKind; 
END; 


FieldPtr = *FieldDescriptor; 


Refer to Chapter 10 for a detailed description of this record. 


Message and Prompt Routines 


The ten message and prompt routines listed below are used to initialize, 
display, and clear messages and prompts. Messages and pro@pts can be 
displayed as the only message/prompt line in the window with any previous 
messages/prompts erased. Alternatively, they can be "stacked"; that is 
displayed above any previously displayed messges/prompts. 


Routine Description 

MsgInit Allocates and initializes a MessageStatus record and 
returns a pointer to the record. 

MsgShowMessage Displays a one-line message after erasing any previous 


message(s) or prompt(s). Returns a True boolean if the 
application should update the rectangle. 
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MsgStackMessage 


MsgShowPrompt 


MsgStackPrompt 


NsgShowError 


MsgShowDecoded 


MsgClearMessage 


MsgClearPrompt 


MsgExit 


Displays a message stacked on top of any currently 
displayed messages. Erases any previous prompt(s). 

Returns a True boolean if the application should update the 
rectangle, 

Dispays a one-line prompt after erasing any previous 
prompt(s) or message(s). Returns a True boolean if the 
application should update the rectangle. 

Displays a prompt stacked on top of any currently displayed 
prompt(s) or message(s). Returns a True boolean if the 
application should update the rectangle. 

Displays a one-line error message after erasing any 
previous message(s) or prompt(s) and then locks the 
keyboard for two seconds. Returns a True boolean if the 
application should update the rectangle. 

Displays an error message specified by a GRiD-OS error code 
after erasing any previos message(s) or prompt(s) and then 
Jocks the keyboard for two seconds. Returns a True boolean 
if the application should update the rectangle. 

Clears any messages currently displayed but has no effect 
on currently displayed prompts. Returns a True boolean if 
the application should update the rectangle. 

Clears any prompts currently displayed and any messaes that 
have prompts stacked on them. Has no effect on currently 
displayed messages if there are no stacked proapts. 

Returns a True boolean if the application should update the 
rectangle, 

Displays one of three messages before exiting the 
application. Allows normal exit “Retrieving subjects: In 
progress", memory exhausted message “Out of memory: Confira 
to exit", or reboot message “System Error: (code) Confira 
to reinitialize systema. 
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CHAPTER 7: BYTE MANIPULATION PROCEDURES 


This chapter describes the byte manipulation procedures, which enable you to 
move, search for, and assign values to individual bytes in memory. They are 
the PASCAL equivalents to the PL/M String Manipulation Procedures (i.e. byte 
strings) as defined in the PL/M-Bé User's Guide. 


These routines provide a very rapid and efficient mechanism for updating the 
bit-mapped screen. By altering the memory allocated to the screen, the 
screen‘’s display will change, 


These routines use parameters of type Bytes to identify areas in memory. A 
segment of memory can be visualized as a one-dimensional array of bytes, The 
parameter of type Bytes acts as a pointer to the first element of the array of 
bytes. 


BYTE ROUTINES 
Routines are provided to move, find, compare, set, insert, and delete bytes. 


WARNING: The two movement procedures can move up to 64K bytes in a segment at 
once, Memory areas are NOT PROTECTED by hardware. Use the "move" routines 
with care. 


MoveBytes Moves data from one location in memory to another. 

MoveReverseBytes Moves data from one location in memory to another starting 
from the end of the data rather than the beginning. This 
allows you to move bytes into a destination that overlaps 
the source location. 


FindByte Searches an array of bytes in memory for a given character, 
and returns its position in the array. 

CompareBytes Compares one memory area with another one te see whether 
they match. They must be the same length. 

SetBytes Sets every byte in the destination area to the same given 
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InsertBytes 


DeleteBytes 


value. 

Inserts bytes into a specified area of memory. The contents 

of the inserted bytes are undefined. This procedure is . 
useful for inserting new elements into arrays, structures, g 
strings, etc. 

Deletes a given number of bytes from an area of memory; the 
wemaining bytes are moved together to close up the resulting 

gap. This procedure is useful for removing elements from 

arrays, structures, strings, etc. 
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CHAPTER 6: MENUS AND FORMS 


Commands can request data from the user by presenting a menu or a form. With 
a menu, the user selects a single value as input to the Compass. Forms allow 
the user to give the computer several values at once. This chapter describes 
the routines and techniques available to programmatically display menus and 
forms. The technique used is known at GRID as "Data Driven Menus and Forms” 
because a predefined data structure determines both the appearance and 
contents of a menu or fora, 


NOTE: This technique requires that you have both the Pascal and PLM 
compilers. There is another, older and more complicated, method of doing 
menus and forms that does not require the PLM compiler. This alternate 
technique is described in Appendix C. 


A special form, the File form which is used throughout GRiD applications, is 
also described in this chapter. 


OVERVIEW OF DATA DRIVEN MENUS AND FORMS 


The basic concept behind using data driven menus and forms is siaple. You 
need two modules. One module is written in PLN and contains data structures 
which specify what your forms and menus look like. The other module is written 
in Pascal and calls Common Code routines to display these menus and foras. 
when the Pascal routine calls Common Code to display a menu or form, it passes 
the name of the PLM data structure representing that menu or form as a 
Parameter. Common Code takes care of the rest, 


Why use PLM at all? Couldn't it all be written in Pascal? Yes it could, but 
Pascal does not let you declare variables with initial values and PLM does. 

If the data structures were declared in Pascal then extra code would be needed 
to initialize them before they could be used. 
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DATA DRIVEN MENUS 


A menu is one of the simplest means pf getting input from the user. GRiD 
menus eliminate unnecessary and repetitive typing. Instead of typing, users 
select standard inputs by pressing arrow keys and CODE-RETURN. 


With Common Code routines, you can add GRiD menus to your programs very 


quickly. Once you‘re familiar with them, they will be easier to program than 


traditional methods 


of getting the user‘’s input. And, they'll make your 


programs easier to understand and to use. 


You don’t have to understand the structure of the entire Common Code in order 


to program a menu. 


You can copy the example code given in this chapter, and 


modity it for your application. 


Typical items for a 


o Parameters to a program. 


menu include: 


instead of any of the others. 


bd Operations to be completed. The program completes the selected 
operation instead of any of the others. 


The sample menu that we illustrate in this chapter is similar to the Transfer 


menu that is used throughout GRiD applications. This basic example is a 


building block that 


you can flesh out or modify to aeet your needs. It 


displays seven items on the screen for the user to select. Each itea 
represents an operation. When one of the items is selected and {confirmed,} 
the computer would perform the selected operation. (To keep the example 


simple, we will not 
operation.) 


show any of the code that would perfors the selected 


A GRID menu returns information telling you which one of the possible menu 
items the user picked. Figure 8-1 shows a sample GRiD menu. All] GRID menus 


resemble this one. 


A menu consists of: 


Menu items A vertical list of objects or operations, such as commands, file 


ee : a = 


Include a file 

Write to a file 

Append a file 

Erasa a file 

Show characteristics of a file 


Sample: 


SENS item and confirm 


Figure B-i: A Gaeple Nenu 
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The program will take the selected parameter 
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titles, or storage media. By confirming an item, the user 
tells the Compass to operate with that item instead of the 
others. The items are display-only fields that the user cannot 
modify. 

Outline A moving indicator that surrounds the current item. A 
triangular cursor never appears within this outline, because 
text can never be typed into a menu. You select an item by 
moving the outline to the desired item and confirming (pressing 
CODE-RETURN). 

Message Line An informational message instructing the user as to what action 
to take with the menu. 


Menu Data Structures end Types 


The DataMenuConfirmed routine that displays menus is given a pointer to a PLM 
data structure when the function is called. The pointer is defined as 
follows: 


SomeArrayOfBytes = ARRAY [i..1] OF CHAR; 
PointerToSomeBytes = *SomeArrayOt Bytes; 
DataMenuType = PointerToSomeBytes; 


The array of bytes being pointed to is the data structure that is defined by 
the PLM module. 


Figure @-2 shows the PLM data structures that define the menu shown in Figure 
8-1, The PLM data structures are almost self-explanatory. The first data 
deciaration (the "SampleMenuTemplate") defines the constants which are the 
menu items to be displayed for the menu. A tilde (*) delimits each menu ites 
and a vertical bar (produced by pressing Code-Shift-;) marks the end of the 
list of items. The second data declaration defines a pointer to the aenu item 
data. Note that names for the two data items, “sampleMenuTemplate" and 
“theSampleMenu" are user defined and that the name “sampleMenuTemplate" 
appears in two places. When you change one then you must change the other. 


POA Gaaple@ aenu HERHEHSEEHEHE/ 


ICL saepletienuTeaplate (#) BYTE PUBLIC DATA 
(‘Save this file*’, 
"Exchange for another file*', 
"Include a file*’, 
‘Write to a file*’, 
“Append a file’, 
‘Erase a file*’, 
“Show characteristics of a file"t‘); 


DCL theSaapteMenu PTR PUBLIC DATA {Bsamp!eMenuTesplate) ; 


Figure 8-2: PLM Data Structures for Saaple Menu 
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Data Driven Nenu Routines 


One Common Code function {DataMenuConfirmed) does all the work to implement 
data driven genus. The DataNenuContirmed function displays the menu you have 
defined in the PLM data structure. It also lets the user select an item by 
pressing arrow keys. Note that DataMenuConfirmed cannot act upon the user’s 
selection until after the user has pressed CODE-RETURN., Pressing CODE~RETURN 
is the only way to indicate that the outlined item in the menu should be used 
for processing. 


The DataMenuConfirmed function definition is as follows: 


FUNCTION DataMenuConfirmed (dataMenu : DataMenuType; 
asgStatus : MessagePtr; 
msg : StringPtr; 

VAR rect : Rectangle; 
keyProcess : WORD; 

VAR selection : INTEGER; 

VAR ch : CHAR) : BOOLEAN; 


When the function is called, it is given a pointer to the PLM data structure 
defining the menu, and pointers to your message area and the proapt to be 
displayed with the menu. It returns the selected item and a Boolean 
indicating whether the menu was confirmed. Refer to Chapter 12 for a complete 
description of the parameters for DataMenuContirmed. 


Data Driven Menu Example @ 


Figure 8-3 Shows the Pascal procedure that displays the senu shown in Figure 
B-1. The Common Code function call "DataMenuConfirmed" displays the menu. 
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{- 
PROCEDURE Samp! eMenu; 
VAR str: StringPtr; 
rect: Rectangle; 
iteaSelected: Integer; 
confirmed: Boolean; 
BEGIN 
str 32 Concatiits (Transfertsg, Selecttsg); 
rect jindowRect; 
Confirmed := DataMenuConfiraed 
(theSaapleHenu, 
msg, 
str, 
rect, 
cursor .keyProcess, 
iteaSelected, 
ch); 


IF contiraed THEN 
BEGIN 
CASE iteaSelected OF 
1; ; {do appropriate action for "save"} 
3 {do appropriate action for "exchange"} 
{ do appropriate action for ‘include"? 
{do appropriate action for "write"} 
( do appropriate action for “append"} 
{ do appropriate action for “erase"} 
{ do appropriate action for "show characteristics"? 
3 { do appropriate action for "print?} 
‘OTHERWISE; 
END; 
END; 
END; 


Figure 6-3: Pascal Procedure to Display Sasple Menu 


Appendix B contains complete source listings and the link command file for a 
progran that displays the sample menu. 


If the user did not press CODE-RETURN to leave the menu, the variable ch 
contains the character which the user pressed to exit the menu instead. Any 
character except CODE-RETURN or Arrow keys will cause the menu to be exited. 
In this example, DataMenuConfirmed does not do anything with ch, but it 
returns the value of the variable "confirmed," so that the calling procedure 
will know whether an item on the menu was confirmed or not. 
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DATA DRIVEN FORMS 


Forms are similar to menus in that they capture information specified by the 
user but they are different from menus in the following ways: @ 


o Forms can let users change the settings of several items. Menus let them 
confira only one item, 

o Users can type their own settings. Forms do not have to limit thea to 
predefined choices . 

o When users press CODE-RETURN, they confirm the settings of all the form 
items, not just the currently outlined setting. 


Forms enable users to change the settings of many parameters with very little 
typing. They replace the tedious practice of stepping through a list of 
parameters and requesting settings (and corrections) from the user. 


o When a parameter’s value must come from a predefined set, forms can force 
the user to choose from correct settings only. The user avoids the 
frustration of typing in a value, only to have the computer reject it. 


o Forms present all the parameters at once. The user decides which parameters 
to change first. 


o Corrections are simple: the user returns to the item to be corrected, and 
changes the setting displayed. No time is wasted by advancing past correct 
values to find an incorrect one. 


From a programmer's point of view, a form is a matrix of fields that has at 


least two columns: a 


Ttem column A column of fields that identify the data being changed. 
They are not used in processing the form's settings. The 
user cannot move the outline into the item column or change 
the items there. 


Setting column A column of fields that the user can modify. The data values 
in the setting column indicate an initial setting, or some 
choice or typed input by the user. The form stores these 
modified settings in its own data structure. The settings can 
be kept stored in the fore or they can be copied into other 
variables in your program. 


Figure 8-4 shows a sample form. 
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Editable numeric field g 1 
Choice only field irst choice 


Editable-choice field A choice 


Editable real number field 5.0980 
Typeface System-wide 
Printer EpsonFs100 
Plotter HP 


e: Fill in form < confirm 


Figure 8-4: A Saaple Fora 
Thiz form illustrates al] the currently defined items for GRiD forms. 
o The first item is an editable integer-number with no choices. The user 


is expected to enter an integer value to set such things as document 
width, colu@n width, and so on. 


o The second item is choice only. The user selects one of the displayed 
choices such as "Display headings” or “Don’t display headings". 


First choice 


Editable numeric field 


Choice only field 
Paibeb te clei ee eet 


o The third item is an editable string with choices. The user can either 
choose one of the available choices or enter a string to specify a 
choice not offered. For example, the user might select the choice to 
display text using window width or can specify the line width to be used 
for display of text. 


firey A& choice 


Editable numeric field 8a 
Choice only field Second choice 
Editable-choice field Zi 


Fditahis rosl number Fiald 


o The fourth item is an editable real-number with no choices. The user is 
expected to enter an real number to set such things as precision. Fora 
items that are editable real numbers will be displayed with four digits 
after the decimal point. If the user enters a number without decimal 
places, the system still treats it as a real number and supplies the 
four decimal digits. 


‘ 
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Editable numeric field 
Choice only field 
Editable-choice Field 
Editable, real number field 
Tupef are 


ea 
Second choice 
28 


Seen - 


If you want some other format, you can dislay an editable string and do 


the cnversion yourself. 
o The fifth, sixth, and seventh 


items are special kinds of choice-only 


items. They display the available font, printer, and plotter files in 


the choice band. 


Built-in GRiD Sx? GRiD 4x7 GRiD 53 


Editable numeric field 
Choice only field 
Editablechoice field 


Editable real number field 4 


Typeface 


Printar 


6a 
Second choice 
26 


UStem—uwi de 
meaner eT 


These items automatically display all] of the files with a Kind of 
"Font", "Printer", or "Plotter" that are in the Programs directories 


when the system was booted. 
displayed in the choice band. 
in the choice band, the addit 
into view. 


Editable numeric field 
Choice only field 
Ecditeble-choice field 


Typeface 
Printer 


Foras Data Structures and Types 


Several Pascal data structures and 


GRiD 4x7 GRiD 53 GRiD 5x7 GRiD 64 PC 


Editable real number field 4 


The user can scroll to the desired choice 
Notice that if all the choices do not fit 
ional choices are automatically scrolled 


2) 
First choice 


oe ais = 


types are used with data driven forms. 


* TYPE SomeArrayOfBytes = ARRAY [1..1] OF CHAR; 


PointerToSomeBytes = *SomeArrayOfBytes; 


This pointer is used to keep track 
of forms at once. It points to an 
labels and choices of the form and 
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of different forms when you have a number 
array that contains the definitions of the 
which also holds the form's data. (The 


@ 


@ 


O 


labels and choices are initialized using the information defined in the PLM 
data structure.) 


# TYPE DataKindType = 
(stringkind, 
numberking, 
choiceOnlyKind, 
fontKind, 
realNumberKind, 
printerKind, 
plotterKind); 


This enumerated type defines all of the different kinds of choice items you 
can use with forms, 


* TYPE DataFormModeType = 
(normal DataForm, 
initOnlyDataForm, 
runOnlyDataForm); 


You can specify three different kinds of forms: noraal, initialize only, or 
run only, When you specify a “normal® data form, the form is immediately 
displayed by DataFormConfirmed and the results are stored in the form when it 
is confirmed. You would use the “initOnlyDataForm" amd "runOnlyDataFora" 
types for more advanced programming techniques. If you specify 
“initOnlyDataForm", the form will not be displayed. A common use of this mode 
is to discover the rectangle that will be available for your form before you 
actually display the form. I[f you call DataFormConfirmed with 
“runOnlyDataFroa", the form is dispayed but it is not initialized. Therefore, 
if you use this mode, you must always call the routine after you have called 
it with the "initOnly" mode. When you call the routine in the “normal” mode, 
the form is both “initialized” and "run". 


* TYPE DataKindAliasType = RECORD 
CASE INTEGER OF 
1: (string : StringPtr); 
2: (number : INTEGER); 
3: (realNumber ; REAL); 
END; 


This record defines the three different kinds of data choices that can be used 
in forms. 


* TYPE DataRowType = RECORD 
changed : BOOLEAN; 
rowKind : DataKindType; 
currentChoice : INTEGER; 
tempChoice : INTEGER; 
theData : DataKindAliasType; 
tempData : DataKindAliasType; 

END; 
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The DataRowType record is the structure where the choice data for each row 
{item) on the form is stored. The contents of this record are as follows: 


changed A Boolean that is set true if the choice for this row was 
changed from its previous setting. You can use this parameter 
as a "dirty" bit to determine if you need to examine the 
record, 

rowkind Specifies one of the seven kinds of possible choices. 

currentChoice An integer identifying the current choice for an item. Qn 
entry, determines which choice will be displayed as current 
choice for each item. On return, contains the choice that was 
confirmed. NOTE: You should always set the current choice even 
if the field consists only of an editable field (set 
currentChoice = 1). Otherwise, the “changed” Boolean wil! not 
be set correctly. 


tempChoice An internal variable used by the function itsel#. Should never 
be changed. 

theData The actual numeric or string data that is the current choice. 

tempData An internal variable used by the function itself. Should never 


be changed. 


The last data type is the form itself. 


* TYPE DataFormType = RECORD 
form : Pointer ToSomeBytes; 
numitems : INTEGER; 
labelsAndChoices : PointerTaSomeBytes; 
choiceLines : INTEGER; 
rows : ARRAY Ci..1] OF DataRowType; 
END; 


The DataForaType record defines the location of the form and its appearance, 
and contains the form’s data. The contents of this record are as follows: 


form @ pointer used internally by the DataForaConfirmed 
function. Initialized to NUL. Should not be changed by 
the user. 

nunitems The number of items on the fora. 


labelsAndChoices A pointer to the PLM data structure that contains the item 
labels and choices to be displayed on the fora. 

choiceLines An integer that determines how many vertical lines will be 
used to display choices. A value of one displays all 
choices on a Single line and scrolling is horizontal (as 
shown in the sample forms). Values greater than one 
display choices vertically within the number of 
“choiceLines" specified and scrolling is vertical. 

rows An array of DataRowType records holding the data that is in 
the fora, 
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Figure 8-5 shows the PLM data structures required to display the form shown in 
Figure 8-4, This example structure can be used as a template for creating 
your own forms. The items that need to be modified when creating a new form 
are marked with numbers, These are described on the following page. 


/eeeeeeeeeenets Saaple 


DCL saapl@Foralteatount LITC72 
DEL sampleForaRowSize LIT (3B 7# 14 tines ites count #/ 


OCL saapleForaLabelsAndChoices (#) BYTE DATA 
(‘Editable numeric field*An integer*!, 
‘Whaice only field*First choice*Secand choice*!’, 
“$Editable/choice field*A text string*A choice*!', 
“Editable real number field*A real nusber*i’, 
“uTypeface™t", 
“sPrinter*t', 
“=Plotter*! "3 


DCL theSaspleFore STRUCTURE 
{fora PTR, 
nualtess INTEGER, 
label sAndChoices PTR, 
choiceLines INTEGER, 
rows (sampleFor@RowSize) BYTE) 


PUBLIC DATA 

(nul Ptr, f# fore, u 
saapleForalteaCount, /* nualtens # 
@saapleForalabel sAndChoices, /# itees uf 


d# choicelines #/ 


Figure B-5: PLM Data Structures for Sample Fora 


@ = The data structures for each form must have a unique name. Thus, if you 


were defining a "properties" form, you would change all occurences of the 
phrase “sample” to “properties” throughout this PLM data structure. 


@ This is the number of items in the form (seven, in our sample). 


@ > This number MUST be fourteen (14) times the number of items in the form. 


(It is used to allocate space for data.) 


@ This is where you specify how the form will look and the characteristics 


of each item, The first character in each line determines what kind of 
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item this is according to the following convention: 


# = - an editable integer-number item. I you want an editable number 
item to initially display blank, you must initialize the nuaber to 
"“-Maxint", (e.g. theSampleForm.rowl1].theData.number := - MaxInt3) @ 


See the example that follows for an illustration of this method. 


- a choice-only iten 

- an editable string and choice item 

- an editable real-number item 

- a font item. A special “Choice only” item of font files. 

- a printer item. @ special “Choice only" item of printer device 
files. 

~ a plotter item. A special "Choice only" item of plotter device 
files. 


tee we 


Following this initial character is the name of the item exactly 
as it is to appear in the form. The item name is terminated by 
the tilde (*) delimiter character. Then the choice band items (if 
any) are separated by tildes and the entire item definition is 
ended with a vertical bar (3). 


The third item in the example form is an editable chaice. It 

contains both an editable string and a choice band. In editable 
choice item definitions, the editable field is whichever one you 
list (define) first. The fields that follow are choice fields. 


@® This number determines the orientation of the choice band, The number 1 
specifies a horizontal choice band as shown in the sample fora. Nuabers 
greater than one specify vertical choice bands of that height. If the @ 
choices don't fit within the choice band, they are scrolled automatically 
(either horizontally or verically) by the DataForaConfirmed function. 


Data Driven Foras Routines 


There are five Common Code routines used in conjunction with data driven 
foras: 


DataForaConfirmed This function displays the defined fora. It is 
Similar to DataMenuConfirmed. Refer to Chapter 12 for 
a complete description of DataFormConfirmed 
parameters, 


UndoDataFora This procedure deallocates all the tables and internal 
structures associated with a form. Its second 
Parameter is a boolean indicating whether you want it 
to erase the area occupied by the form. You should 
ALWAYS call this after displaying a form. 


FreeStringsinDataFora This procedure frees all the strings in a data form. 


You should only cal] this after you have copied any 
strings from the farm into permanent variables. 
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IMPORTANT: There is no reason that you have to store 
the values of a form in separate variables. You can 
leave them in the form. This latter method is often 
easier. If you do leave the values in the form’s data 
structure then you should never call 
“FreeStringsinDataFora". 


ExactCopyO#String This function makes an exact copy of an indicated 
string and returns a stringPtr to the copy. (The 
“CopyO#String” function described in Chapter 5 is 
similar, but returns a string with .len set equal to 
«max, The exact copy will have .len set to the 
current .len of the indicated string. 


StringOfForalten This function returns a stringPtr to the text actually 
displayed in a form item. It would be useful if you 
wanted to know the text of a choice selection as 
apposed to the number of the choice, 


Data Driven Forms Exaaple 


Figure 8-6 shows a Pascal procedure that displays the form we have been 
looking at. It has been marked into four areas which will be explained next. 
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PROCEDURE SaepleFora; 
VAR iteaSelected: Integer; 
confirmed: Boolean; 


rect: Rectangle; 
str: StringPtr; 
BEGIN 


str := ConcatLits (OptionsMsg, Fill[nForatsg); 


{ Copy variables inte Data driven fares structure. The variables can be kept 
permanently in this structure. } 
KITH theSaapleFora 00 


BEGIN 
rowst 1), theData. nuaber += theNuaber; 
rows(1),currentChoice my 
rows(2},currentChoice = curChoice2; 
rows[3]. theData.string = ExactCopy0fString (theString); 
rows(3J.currentCheice t= curChoiced; 
rows(4], theData.realNuaber := theRealNuaber; 
rows[4}, currentChoice se dy 


rows(S].currentChoice += curFont; 
rows(o}.currentChoice := curPrinter; 
rows(7].currentChoice := curPlotter; 
END; 
rect := windawRect; 


confiraed := DataForaConfiraed 

(theSaapleFora, 
noraalDataFora, 
asg, 

str, 

rect, 

cursor. keyProcess, 
chy 


IF confiraed THEN 
WITH theSaapleFora DD 

BEGIN 
theNvaber t= rowsl1]. theData. number; 
curChoice2 := rows{2].currentChoice; 
IF rows{3).currentChoice = 1 THEN 

theString i= ExactCopyDfString (rows(3), theData. string); 

curChoice3 := rows{3}.currentChoice; 
curChoiced := rows(4].currentChoice 
curFont = := rows{5).currentChoice; 
curPrinter := rows(6], currentChoice; 
curPlatter := rows{7J.currentChoice; 
FontSethth (curFont, code); 

END; 


FreeStringsIndataFora (theSaeplefora) 
UndoDataFora (theSaapleFora, TRUE); 


END; 
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Figure @-41 Pascal procedure for displaying form 


@_~ The vatues of the items in a form must be stored between each instance of 
i) the form. In this example these values are stored in separate data items. 
& Before displaying the form the stored values are copied into the form's 
data structure. That is what is happening here. 


The items on the right of the assignment statements are variables where 
the settings of the form are stored, The “rows" on the left side of the 
assignment are record items in "theSampleForm” record, (See the 
description of DataFormType earlier in this chapter). 


The third item in the form is an editable string. We must make a copy 
of the string because the form will be disposed of later and we don’t want 
to lose the original string. 


@ DataFormConfirmed displays the form, It is similar to DataMenuConfirmed. 
Refer to Chapter 12 for a complete description of DataFormConfirmed 
parameters, 


@® 14 the form was confirmed then we want to copy the new values back into 
the permanent variables. This is done here. The new font is also loaded 
with the call to "FontSetNth". 


@ = "FreeStringsInDataForm” does just that. You should only call this after 
you have copied any strings from the form into permanent variables. 
IMPORTANT: There is no reason that you have to store the values of a form 
in separate variables. You can leave them in the form. This latter 
method is often easier. If you do leave the values in the form’s data 
structure then you should never call “FreeStringsInDataFora". 


“UndoDataForm" deallocates ali the tables and internal structures 
associated with a form. Its second parameter is a boolean indicating 
whether you want it to erase the area occupied by the form. You should 
ALWAYS call this after displaying a form. 


Appendix B contains complete source listings and a link file for a program 
that displays this form. 


Example Notess 


You can reduce the size of your program and make it more readable by placing a 
procedure shell around the calls to DataMenuConfirmed and DataFormConfirmed. 
Onty three parameters would then be required to display a menu and two for a 
form, (the menu or form’s data structure, a stringPtr for the message, and 
the itemSelected for a menu) The other parameters used with DataForaConfirmed 
and DataMenuConfirmed are usually global variables. 


There are two ways of storing the data obtained from a form. The method shown 


in Figure 8-6 transfers the data into variables which are separate from the 
form, However, you could leave the data in the form. The latter case will 
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probably create less code. 


Tf you leave the data in the form then you shouldn't call 
“FreeStringsinDataForm". You should always cali “UndoDataForm" because it 
frees all the internal tables associated with a form. 


THE FILE FORM 


The File form is a special form that is used throughout GRiD applications to 
simplify implementation of the Transfer command (CODE-T). Figure 8-7 shows a 


typical Transfer menu. 


ete eae 
change for another file 


Include a file 
Write to a file 


Append a file 
Erase a file 
Shou characteristics of a file 


Sample: Select item and confirm 


Figure 8-7. & Typicai Transfer Menu 


When the user selects and confirms an item from the Transfer menu, a File form 
similar to the one shown in Figure 8-8 can be displayed by calling the Common 
Code function FileFormConfirmed. 


Device Hard Disk 


Subject 

Title 

Kind ex 
Password 


Next action Get naw file and its application 
Save changes Before settina new file 


Exchange: Fill in form and confirn 


Figure 8-8 A Typical File Fora 


The FileFormConfirmed function is similar to the DataFormContirmed function in 
several ways. Both functions display a form, handle movement of the selection 
outline when the user presses the arrow keys, and return with the selected 
items when the form is confirmed, With FileFormConfirmed, however, the items 
on the form are pre-defined instead of being defined by the programmer. 


You can vary the content of the form slightly depending on the activity that 
is being initiated. For example, the last item on the form ("Save changes") 


need not be displayed unless 


you are leaving the current file and it has been 


altered since the last time its contents were saved. 
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Qev ice Hard Disk 
e, 


Subject 
Title 
Kind ex 


Passuord 
Next action Get neu File and its application 


Exchange: Fill_in Form and conPirn 


Similarly, the second-to-last item ("Next action") need not be displayed for 
such operations as "Erase a file" or “Include a file” when you are not leaving 
the current file and “following” to another file and/or application. 


Device Hard Disk 


Include: Fill in form and confirn 


The FileFormConfirmed function lets you specify when these two items should or 
should not be displayed. 


When the "Next action” item is displayed, two different conbinations of 
choices can be displayed for the "Next action” item. If the Transfer 
operation being initiated is one where the user is given the choice of 
“following” to the selected file and immediately beginning work on that new 
file, them you would display the following three choices for “Next action": 
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PO (PEStT eee (Crergeeee [Pesegpeeepeeerg rece pUenegered [OCC B ety 


P_current 
et neu File and its application 
Get neu File only 


Dev ice Hard Disk 
Subject connoncode 
Title 

Kind Tet 
Passuord 


Hest action 


Write: Fill in form and contirn 


These are the choices that GRiD applications display for “Write to a file" and 
“Append to a file". If the Transfer operation is one such as "Exchange for 
another file” that precludes keeping the current file, then the first choice 
("Keep current file") for “Next action” can be suppressed. 


When you call the FileForaConfirmed function you can set the initial choices 
that are to be displayed for each item. For example, for “Append to a file" 
operations, GRiD applications initially set the "Next action” item in the File 
form to the "Keep current file" choice since it is assumed that this will be 
the choice must frequently used. When the form is confirmed, the function 
returns the actual choices selected by the user. 


Pathnane Defaults 


When the File form is displayed, you can specify which parts of the pathnane 
(Device, Subject, Title, and Kind) are to be left blank and which parts should 
be defaulted (either to explicitly defined settings or to the current prefix). 
BRiD applications typically default the device and subject to the current 
prefix, leave the Title blank (don’t default), and default the kind to the 
same kind as the current file. For example, if the current prefix were ‘Hard 
Disk'Sample’, GRiDWrite would let the Device and Subject default to the 
prefix, and would default Kind to Text; Title would be left blank. 
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Dev ice Hard Disk 

Subsect 
Title 

Hind Tent 


Fassuord 
Nest action Heep current File 
Save changes Before getting new File 


Write: Fill in Porn and conPirn 


Notice that the selection outline and cursor are positioned at the Subject 
item. The FileFormConfirmed function also lets you specify the pathname item 
on the form where the selection outline and cursor should originally be 
positioned when the form is displayed. 


We will summarize the typical settings and values used by GRiD applications 
when displaying the File form after we have described the data types used in 
conjunction with FileFormConfirmed. 


File Form Constants and Data Types 
Seven constants are defined for the FileFormConfirmed function: 


DevicePart 
SubjctPart 
TitlePart 
KindPart 
PasswordPart 
ExchangePart 
SavePart 


few o ng 


These constants correspond to the seven items that can be displayed on the 
File form. The ExchangePart corresponds to the "Next action" item and the 
SavePart corresponds to the "Save changes" item 


Six data types are used with FileFormConfirmed. 
#TYPE FFModeType =(FFGet, FFPut) 


This enumerated type is used in combination with other conditions to determine 
what message (if any) the function should display below the File form. We 

will describe the messages and the circumstances when they are displayed after 
this discussion of data types. NOTE: The nomeclature of “Get” and “Put” is a 
carryover from an earlier, more primitive Common Code function and, while not 
very apropos in this context, they have been preserved for historical reasons. 
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*#TYPE FFExchangeNode 
FFExchangeAndSave); 


FFExchangeMode determines 
"Save changes” items as f 


FFNoExchangeOrSave 


FFExchange 


FFExchangeAndSave 


#TYPE FFExchangeResu 
FFExchangeApplicatioa 
NextAction??) 


FFExchangeResult specifie: 
action" item should be an 
confirmed by the user. 

If the initial value in Fi 
FFExchangeApplication, th 
is not allowed and will n 
example, if the activity 
applications initially se 


= (FFNeExchangeOrSave, FFEachange, 


whether the form displays the "Next action” and 
ollows: 


Display neither "Next action” nor “Save changes". 
Typically used for such activities as “Erase a file” 
and "Show file characteristics" when it is apparent 
that the user is remaining within the current file 
and application. 

Display "Next action" only. Typically used for such 
activities as “Append to a file" or "Write to a file" 
when the user may be leaving the current file or 
application but there have been no changes made to 
the current file since the last time it was saved. 
Display "Next action” and “Save changes". Typically 
used for such activities as “Append to a file” or 
“Write to a file" when the user may be leaving the 
current file or application and there have been 
changes made to the current file since the last time 
it was saved. 


Jt = (FFDontExchange, FFExchangeFiles, 
ins); (PETER -- HOW ABOUT RENAMING THESE TO 


s what the initial or default choice for the “Next 
4 indicates which one of the choices was selected and 


FExchangeResult is either FFExchangeFiles or 
en the "Keep current file" choice for "Next action" 
ot be displayed as a choice in the form. For 
being initiated is "Exchange for another file", GRiD 
t FFExchangeResult to FFExchangeApplications so that 


the form appears as follows: 
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ce 


@ 


Get neu Fi 


Bev ice Hard Disk 

Subject Sanple 

Title 

Kind Text 

Passuord 

Newt action [bet _neu Sand its application 
Save changes BeForé getting new File 


Fill in Forn and conFirn 


The logic here is that if the user is obviously going to be exchanging either 
the current file or application then you do not want to present the 
meaningless choice of “Keep current file". In situations such as “Append to a 
file” or write to a file", however, where the user may want keep the current 
file, you must set FFExchangeResult to FFDontExchange in order to display the 
“Keep current file” choice. 


#TYPE FFSaveResult = (FFSaveFile, FFDontSaveFile); PETER - HOWABOUT 
FFSaveChanges??) 


FFSaveResult specifies what the initial or default choice for the "Save 
changes” item should be and indicates which one of the cheices was selected 
and confirmed by the user. 


#TYPE FFDefaultType = (FFDefaultThis, FFDetaultThisStartHere, 
FFDontDefaultThis, FFDontDefaultThisStartHere); 


FFDefaultType specifies which of the File form pathname items (Device, 
Subject, Title, Kind) should initially be left blank and which should be 
supplied from the default values contained in the pathName parameter of the 
FileForaConfirmed function. If It can also specify the initial location of 
the selection outline and cursor on one of these four items. If you specify 
"DontDefaultIf", that part of the pathname is left blank. I you specify 
"Default" for Device or Subject and do not supply a default setting, the 
current prefix for these items is used. As mentioned before, GRiD 
applications use the prefix default for Device and Subject and supply a Kind 
default that is the same as that of the file currently being operated on. The 
Title is usually left blank (no default). 


*TYPE FFDefaultTypeRec = ARRAYCDevicePart..KindPart) OF FFDefaultType; 
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This array contains elements for each part of the pathname. Each element 
specifies whether to use that part of the pathname as a default in the fora. 
g 


File Form Messages 


The FileFormConfirmed function can generate six different messages to prompt 
the user when the File form is confirmed. These messages ask the user to 
verify that a new file is to be created or that an existing file is to be 
overwritten or notify the user that the form has been incorrectly filled out. 
These messages are displayed in the same area as the user~supplied message and 
are automatically removed and replaced with the user-supplied message when the 
user presses any key (except £SC or CODE-RETURN). The messages and the 
situations when they are generated are as follows: 


"Contirm to overwrite old file’ 

o fileMode parameter for FileFormConfirmed is not “ald file" 
o AND FFMode = FFPut 

o AND the specified file already exists 


"Confirm to create new file" 

o file or subject does not exist 

o AND FFMode = FFGet 

o AND fileMode parameter for FileFormConfirmed = "update file” 
o AND FFExchangeResult is not FFDontExchange 


"All items except password must be filled in" 
o any item except password in the fora is blank when the form is 


confirmed @ 


"Wildcards not allowed here" 
o the wildcard character (CODE-W) is entered in an iter 


"Use GRiDManager to assign passwords" 
o file or subject does not exist 
o AND Password item is filled in 


“DEL CTRL * * t not allowed here 
o if any of these characters are entered in the fore 


Typical FileForaConfiraed Settings 


Table 8-1 illustrates how a typical GRiD application sets the various 
parameters when calling FileFormConfirmed. You will notice that the @ajority 
of the parameter settings are the same regardless of which Transfer command 
activitiy is being initiated. 
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Table 8-1. Typical parameter settings for FileForaContirmed 
FFRode Default attach file access Exchange FFExchangeResult 
Dey Subj Title Kind Mode Node ode (Taput) 

Save FFPut - Yes Yes No Yes True Update Update Nofx/NoS Don’t Exchange 
Exchange FFGet Yes Ves No Yes True Update Read ExAndSave Don’t Exchange 
Include FFfet Yes Yes No Yes True Old Read WoEx/NoS Don’t Exchange 
Write FrPut Yes Yes No Yes True New Update ExAndSave Don't Exchange 
Append FFGet Yes Yes No Yes True Update Update ExfndSave Don't Exchange 
Erase FF6et Yes Yes Ho Yes True Old Update HoEx/NoS = Dont Exchange 


Characteristics FFGet Yes Yes No Yes False Old Update NoEx/NoS Don‘t Exchange 


Exchanging Applications 


1f the File form is confirmed and the user has specified a "Next action" of 
"Get new file and its application", the tunction FFExecuteCommand is used to 
get the new application and file. This function requires only the file nane 
(as returned by the FileFormConfirmed function) as its input. It passes this 
file name to the system Executive which retrieves the appropriate application 
to work with that file. For example, if you pass a file name with a Kind of 
“Text” to FFExecuteCommand, the Executive looks for an application program 
with a Kind of “Run Text” and loads that program and the specified text file 
into memory. 
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CHAPTER 9: FONTS 


The Common Code package provides several routines to simplify the use of 
multiple fonts (also know as typefaces) within applications. The font 
routines let you specify (either by mame or index number) the font that is to 
be loaded into memory and used by an application as the current fant. 
Routines are also available to let you obtain the name or index nuaber of the 
current font and to determine how many fonts are currently available in the 
system. 


The font-related routines are as follows: 


Call Purpose 
FontCount Returns the number of fonts available in the system. 
FontSetNth Sets the font specified by its index number (Nth) as the 


current font and loads it into memory. 
FontSetName Sets the font specified by name as the current font and loads 
it into memory. 


FontNthName Returns the name of the font specified by its index number 
«Nth), 
FontGetN Returns the index number {N) of the font specified by its name. 


Refer to Chapter 12 for detailed descriptions of each of these calls. 


During the boot procedure executed by the Compass, Common Code builds a list 
of such things as printers, plotters, and fonts that are available in the 
system. This information is made available to application programs so that it 
can be displayed in forms, such as an option form. (See Chapter 8 for a 
discussion of data-driven forms.) After such a form has been confirmed, the 
DataForaConfirmed procedure returns an integer that indicates which font has 
been chosen as the current font. This integer can then be used by FontSetNth 
to load that font into memory. For example, the following example function 
(FontChanged) compares two variables (tempCurFont and curFont) to see if the 
present font {curFont) is the same as the value returned from 


Fonts 9-1 


DataMenuConfirmed (tempCurFont). 
new font into menory. 


FUNCTION FontChanged : BOOLEAN; 
VAR curFont, teapCurFont : INTEGER; 
BEGIN : 
FontChanged := FALSE; 
IF teaCurFont <> curFont THEN 
BEGIN 
FontSetNth (teapCurFont, code); 
TF code <> okCode THEN 
DisplayError (code) 
ELSE 
BEBIK 
curFont := teapCurFont; 
FontChanged := TRUE; 
END; 
END; 
END; 


If it is not, FontSetNth is used to 


load the 


FontNthName can also use the index integer returned by DataFormfonfirmed to 


obtain the name of the current font. 


An application might need the name of 


the current font so it cab write this name into the Common Properties record 


associated with the current data file. 


The following example procedure 


(WriteFontName) obtains the name of the current font using FontNthName and 


(See C 


then writes that name to the common properties record of the data file. 


Chapter 4 for a discussion of Common Properties.) 


PROCEDURE WriteFontNaae; 
VAR curFont: INTEGER; 
fonts StringPtr; 
BEGIN 
font := FontNthNase (curFont); 
IF fant <> NEL THEH 
BEGIN 
WriteByte (comeonPropsBytel ; 


WriteWord (font*.len + 15 (record length} 


WriteByte {fontProps!D); 
FOR i := 1 TO font*.Jen DO 
WriteByte (ORD (font*.charsli3)); 
FreeString (font); 
END; 
END; 


Similarly, when an application first reads in a data file, it can examine the 
Common Properties record of the file to obtain the name of the current font 
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for that file. FontSetName can then be used to load that font into memory if 
it is not the font currently being used. An application can obtain the index 
number associated with a font name by using the FontGetN call. For example, 
the following example procedure (ParseFontName) reads the name of the current 
font for a data file from the common properties record, then sets that font as 
the current font using FontSetName, and then obtains the index number 
associated with that font using FontGeth. 


PROCEDURE ParseFontNaae; 
YAR chs INTEGER; 
font: StringPtr; 
codes WORD; 
BEGIN 
font := NewString (maxFontLength); 
font*.len := Min (aaxFontLength, pRecord*. coasonProps. length-1; 
FOR ch s= 1 10 font*.len 0D 
font*.chars(ch} := pRecord*,commonProps. textStringlch]; 
FontSetNaee (font, codel; 
TF code = okCode THEN 
BEGIN 
InitFont; (Initialize VARs based on font size) 
curFant 2= FontGetN (fant); 
END; 
FreeString (font); 
END; 
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CHAPTER 101 FIELDS 


This chapter describes the constants and data structures used with fields and 
the routines available to display and edit individual fields. 


To the user, a field is a rectangular area on the screen that contains text or 
numeric values. It can be filled in by the user or the system, 


To the programmer, a field is a data structure that contains a text string and 
formatting information for that text. The Common Code Provides procedures for 
formatting the text and displaying the text on the screen. 


The contents of a field can be left-aligned, right-aligned, or centered. 
Fields can contain more than one line of text. There are four types of 
fields, designed to protect data or enable the user to interact with it. 


Editable Editable fields allow the user to edit their values by 
typing, backspacing, or pressing arrow keys to move within 
the field. 

Display-Only The user cannot alter the values of these fields. 

Choice Choice fields can contain only settings from a predefined 


list. They are used only within forms, as described later. 


Editable-Choice Editable-choice fields can contain settings chosen from a 
predefined list, or the user can edit their values by typing, 
backspacing, or pressing arrow keys. They occur only in 
forms, as described later. 
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CONSTANTS 
The following constant defines the character location of a field, in pixels: G 


CONST bottomMargin {= 1) distance from the lower 
field boundary to the 
one-pixel line beneath 
the descenders 


The other parameters that determine character location are handied by the 
Window-related calls such as charHeight, baseLine, lineHeight, and 
rightNargin. Refer to the GRiD-OS manual for illustrations af these 
parameters. 


DATA STRUCTURES 
# TYPE Alignment = (leftAlign, centerAlign, rightAlign); 


Alignment controis whether the contents of a field are left-justified, 
right-justified, or centered with regard to the field boundaries. All lines 
in a multi-line field share the same alignment, though each line is aligned 
separately. 


# TYPE FieldKind = 
PACKED RECORD 
editable, choice, editableChoice, numeric: Boolean; G 
align: Alignment 
END; 


Fieldkind specifies whether a field can be edited by the user and whether the 
user can use choice arrows to obtain the field’s value. It includes 
specifications for formatting numbers and aligning text. 


WARNING: editableChoice is a special status bit kept by the field package. Do 


NOT modify it. You specify editable-choice fields by setting the variables 
editable and choice to True. 
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* TYPE FieldDescriptor = 


RECORD 
box: 


Rectangle; 
StringPtry 


kind: FieldKind; 


The FieldDescriptor is the fundamental structure that describes a field and 


tex 

END; 
its data. 
box 


text 


kind 


fee 


- 


Defines the size of the field and its display location within the 


window, 


A pointer to the GRiD string variable of the field's text 


Getermines whether the field 15 an editable field, a choice field, 
both, or neither, according to these combinations 


editable 


False 


True 


True 


* TYPE FieldPtr 


@ 


choice 


True 


False 


True 


Resulting field 


A display-only field. 

It can be displayed, but not 
edited. For example, an itea 
on a menu. 


A choice field. 

The user can choose its setting 
from among several predefined 
options. Only the displayed 
options can be chosen, 

because the field cannot be 
edited, 


An editable field. 

Tt may be edited with the 
CODE, arrow, and BACK 
SPACE keys, including 
CODE-BACKSPACE (erase 
previous word), 


An editable-choice field. 
Users can choose among 
several predefined field 
values that are displayed, 
or they can write and edit 
their. own values in the 
field. 


“FieldDescriptor; 
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FieldPtr pointers will enable you to keep track of FieldDescriptors directly, 
and thus, fields and their contents. 


G 


# TYPE FieldEditResult = (ignored, processed, outOfField, bufferFull, 
fieldFull, escaped, ok}; 


Many routines return the FieldeditResult after performing their functions. An 
out0f¢Field condition signifies that the user tried to move outside the current 
field, The FieldfditResult should be used to verify successful display of a 
character and to control movement between fields. See the FidEditField 
routine in Chapter 12 for a desciription of the interpretation of these 
results. below. 


* TYPE CursorDescriptor = 
RECORD 
field: FieldPtr; 
pos: Word; 
place: Point; 
on: Boolean; 
keyProcess: Word; 

END; 


The CursorDescriptor record stores the !ogical position of the cursor position 
where text may be inserted or deleted in a field. 


field Points to the field descriptor of the current field to be edited 


pos The character offset within the field where the next character should 
be inserted. 


place The x,y window-relative pixel coordinate of the tip of the cursor 
ican. 


on Controls the cursor blinking and its on/off status. FidSetCursor 
initializes the cursor to the off state. 

keyProcess contains the process identification number (PID) of the cursor’s 
process. 


NOTE: Do not set the place, on, or keyProcess elements; the interface routines 
set them directly. 
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FIELD ROUTINES 


we) Common Code provides routines to position and draw the cursor, edit and 
display fields, move fieids and format multi-line fields. The available 
routines are summarized below. Refer to the alphabetically ordered function 
and procedure descriptions in Chapter 12 for complete details on each of the 


routines. 

FidStartkeys "Initializes" the cursor by starting a process to control 
the cursor. It puts the PID of the process into 
cursor. keyProcess. 

FldSetCursor Sets the cursor at the last character position in a 
specified field. The procedure does not alter the 
display. 

FldSetPos Sets the x-y pixel coordinate for the place element of the 
cursor. An application can set the cursor to any 
character position in the field. The display is 
unchanged. 

FidDrawCursor Makes the cursor visible and sets the cursor blink count. 

FidEraseCursor Erases the cursor from the display without affecting its 


position in the field or in the window coordinates, and 
sets the blink count. 

FldReadKey Waits for an interrupt signifying that a key has been 
pressed. If no keys are pressed for a certain time 
interval, the function blinks the cursor, and then resumes 
waiting for a key to be pressed. If a key is pressed, 
then the function returns the character. 

FidEditField This all-purpose routine inserts values into the field’s 
character string, performs various key functions, and 
updates both the display and the cursor. 

FldinsertinField Inserts a character in the field at the cursor’s current 
character position, and verifies its insertion by 
returning True or False. It does not redraw the display 
on the screen. Most applications should call FldEditField 
instead. 

FidDrawField Erases the given field and then redisplays the field's 
text string. Call it when you need to display initial 
values or redraw the updated value of a single field. 

This procedure accomodates multi-line fields with 
word-wrapping, but does not word wrap the last line of the 
field. 

FidDrawFieldChars Draws the field's text string without erasing the field 
first. This procedure accomodates multi-line fields with 
word-wrapping, but does not word wrap the last line of the 


field. 
FidInvertChar Performs an exclusive OR operation with a field’s screen 
display to change a character position to inverse-video. 
FidHilightField Draws an outline box around the field. 


FidDimHilightField Draws a one-pixel dashed outline box around the field, 
leaving a one-pixel space from the field boundary. 


FidFormatLine Examines the text of a FieldDescriptor and determines 
where the text should appear on each line of a multi-line 
— field. 
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CHAPTER 11) TABLES 


Common Code includes routines to initialize, edit, and display tables of 
fields, which contain string values. Tables are collections of fields 
gathered together as a matrix. They are convenient for displaying large 
amounts of numerical data or for putting text into a tabular format. 


Tables consist of editable fields, though the fields could be modified to 
become display-only in order to protect the field contents. Each field in a 
table is called a cell. 


Tables are easier to use than individual fields. The Common Code has defined 
procedures for moving from cell to cell, and for controlling the cell that is 
to be edited. Automatic scrolling has been developed for tables, and several 
cell functions have been defined to operate upon selections of cells. 


CONSTANTS 


The constant, nowhere (= 65535), is a possible value of anchor (below) to show 
that a selection has not been anchored. 


These constants have Boolean values: 


editableField True 
nonEditableField False 
allocText True 
dontAllocText False 
disposeText True 


dontDisposeText False 
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DATA STRUCTURES 


Figure 11-1, "Cell Table Pointer Structure," shows how the following data 
structures are related to one another. 


Field Pointer 


corm, and only one 
From the cursors 


Field 
Descriptor 


Screen 
Pointer 
Column, 

Pointer? 


Field 
Pointers 


Field Pointer 
Field 
Descriptor 


Painter 
[4,4) 


Pointer 


To reference the ist character ti] £65535] 
of cell table [4,4] “chars! 
table screen L41°L4]" tent .charsli] array of characters 


Figure !i-1. Cell Table Pointer Structure 


# TYPE ColArray = ARRAY {1..2048] OF FieldPtr; 


Each element of the ColArray points to a field pointer (and ultimately to a 


field and its value). Effectively, each column array is a column of a table, 
and elements of the coluan array refer to successive rows of the table. The 


fourth element of a ColArray would refer to the fourth row of the specified 
coluan in a table. The field pointers on the “successive rows" lead 
eventually to the values of the fields. The value 2048 is a dummy value -- 
the table package includes variable allocation routines as well. 


# TYPE ColPtr = *Colarray; 


Points to a column array, and effectively to a column of the table of field 
values. 


# TYPE BcreenArray = ARRAY £1..2048] OF ColPtr; 


Each element of a ScreenArray points to a ColArray, so the third element of a 


screen array would refer ta the third column of a table. 
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* TYPE ScreenPtr = “ScreenArray; 


A screen pointer refers to the screen array of a CellTable, i.e-, to the table 
structure containing a matrix of fields. 


# TYPE CelliId = RECORD col,row: Integer END; 


The CellId allows application pregrams to reference fields in a 
two-dimensional table. The CellIds in a CellTable structure are independent 
of window scrolling, 


# TYPE SelectionRangekind = 
(celiRange, textRange, rowRange, colRange); 


SelectionRangekind specifies whether the selection comprises the text within a 
cell, a group of cells, or several rows or columns of cells. 


* TYPE TableSelection = RECORD 
cell: Cellid; 
pos: Word; 
rangeKind: SelectionRangekind: 
END; 


The TableSelection structure contains an anchor selection, along with the kind 
of selection range. If rangeKind = textRange, then TableSelection.pos 
contains the anchoring character position within the text of one cell, If 
rangekind is any of the other ranges, then TableSelection.cell contains the 
CellId of the anchoring cell. 
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* TYPE CellTable = 
RECORD 
colPerScreen,rowPerScreen: Integer; 
screen: ScreenPtr; 
movingCell, currentCell, scrollCel] : Celiid; 
visibleRect: Rectangle; 
constraint, visible: 
RECORD 
top, left, bottom, right: Integer; 
END; 
textCursor: Cursor; 
editMode: (normal, command); 
commandChar: Chary 
rangeKind: SelectionRangeKind; 
whichParameter: 0..103 
hilightKind: (noKilight, dia, bright, splitHilight); 
gap: Point; 
anchor: TableSelection; 
sourceAnchor, sourceCurrent: TableSelection3 
commands: Keys} 
hilightOn, verticalGrid, horizontalGrid, 
frame, bottomFrame, rightframe: Boolean; 
headingRows: Integerj 
headingCols: Integer; 
END; 


The CeliTable contains the information needed to keep track of a table of 
fields (cells), their cursor, and other display parameters such as 
highlighting, anchoring, and editing/command modes. Ceilld’s begin at 1,1 
unlike the screen and window pixel coordinates. Figure 11-21 shows the layout 
of fields within a cell table, 
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window G. > 
visibleRect.topLaft .« 
y 


The frame surroaundine the 
VisibleRect. The frame lies 
ubside the VisibleRect. 

UE Na 


este 


cell .13 


gap.y=l pixel 


represents 3 field. 
See Figure 16-1. 


Figure t1-2. Fields in a Cell Table 


colPerScreen 
rowPerScreen Designate the number of columns and rows of fields that 
exist in a particular CellTable. These can be specified 
when initializing a CellTable, After they have been 
initialized, they can be changed using TblAddCol and 
TbiAddRow. Only change them using these calls, however, 
because the dispose routines use them to determine how much 
memory to deallocate. 

A pointer to a screen array (and from there to a column 
array, then to a field designator, and finally to a field's 
text string). 

Useful in applications which require a second inverted 
outline to move while the ordinary outline remains in place. 
In selections, the anchor.cell outline remains at the anchor 
position, while the currentCel!l and movingCell move to make 
the cell selection. 


screen 


movingCell 


In the worksheet editor, the 
manipulated to generate cell 
currentCell] outline stays in 


currentCell The Cellid of the cell which 


movingCell outline can be 
references while the 

place. 

currently contains the cursor. 


This is a read only value. If you want to change the 
location of the cursor, use TbhlSetCurrentCell. 

The absolute Cellid of the top left cell in the CellTable 
displayed on the screen. In easy case scrolling, it is 
always (1,1). In difficult case scrolling, it is the 
visible top left cell, not the logical top left (the Cellid 
of the logical top left cell is (1,1)). For example, after 


scroliCell 
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visibleRect 


constraint 


visible 


textCursor 
editMode 


commandChar 
rangeKing 


whichParaneter 


hilightKind 


gap 

anchor 
sourceAnchor 
sourceCurrent 


commands 


hilightOn 


verticalGrid 
horizontalGrid 
frame 


bottoaFrane 


scrolling, scrollCell could equal (5,7) -- meaning that the 
absolute address of the top left cell on the display screen 
is (5,7). 

A clipping rectangle defined in pixels based on the window 
size. It displays all or part of the cells defined to be 
"visible" (see below). The visibleRect is initialized to 
the rectangle between topLeftMargin (an input to 
ThlInitTable) and windowExtent. 

Defines the cells that the cursor can move into. It must be 
a rectangular area, defined in Celli¢d coordinates. 
Specifies a rectangular area of all cells that are fully or 
partially visible on the display screen. It is defined in 
terms of Cellids, not pixel coordinates. The visibleRect 
clipping rectangle can clip these visible cells. 

A cursor associated with this CeliTable’s field values. It 
consists of the cursor defined in the field package. 
Indicates whether a normal (text input) mode or a command 
mode is in effect. 

A character used to store command mode characters. 
Indicates which type of range has been selected, whether 
text within a cell or a group, row, or column of cells. 
Indicates the parameter the command requires the user to 
input next. If a command needs its third parameter, then 
whichParameter = 3. 

Registers the type of highlighting, either none, bright, 
dim, or splitHilight. The splitHilight kind allows two cell 
outlines on the display at once, a bright outline and a dim 
one. Both should appear when the currentCel] breaks away 
from the movingCell. 

The x and y pixel gap between fields in the table. 

Consists of a rangeKind, a Cellid, and a character position 
within a cell, so that anchoring may be based on groups of 
entire cells or on character positions within a cell. 

In commands that require two selection areas, it contains 
the top left position of the first selection. 

In commands that require two selection areas, it contains 
the bottom right position of the first selection. 

Set of Keys. The keynames in this set define the selection 
command keys that operate with a particular cell table. 
These correspond only to the commands that require a 
highlighted selection of text or cells. 

Specifies whether the highlighting appears on the display. 
Highlighting includes the cursor, the celi outline, the 
split outline, the “additional” outlines (if any), and the 
inverse video highlighting for selections. 

Controls whether vertical lines are drawn to separate the 
fields. ‘ 

Determines whether horizontal lines are drawn to separate 
the fields. 

Determines whether a one-pixel frame is drawn outside the 
visibleRect. 

Determines whether a one-pixel frame is drawn beneath the 
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last row of cells. 1t appears only when the last raw of 
cells is displayed on the screen. 

i) rightFrame Determines whether a one-pixel frame is drawn beside the 
lest (rightmost) column of cells. It appears only when the 
last column of cells is displayed on the screen. 

headingRows An integer representing the number of rows, starting from 
the top of the table (not just the visible part of it) that 
can be displayed but into which the cursor and cel) outline 
cannot move. 

headingCols An integer representing the number of coluans, starting from 
the left of the table, that can be displayed but into which 
the cursor and celi outiine cannot move. (Forms have 
headingCols = 1.) 


# TYPE TableCommandResult = (tableCommandProcessed, 
ourobouros); 


The result specifies whether the command was successfully processed, or 
whether it tried unsuccessfully to write over its own operands in the table 
(the "“ourobouros” result}. (The ourobouros is a mythic symbol of infinity, a 
snake eating its own tail.) 
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TABLE ROUTINES 


The paragraphs that follow summarize the routines available to wark with 
tables. Complete descriptions of each of the routines are provided in the 
alphabetically ordered Chapter 12. 


Allocating and Disposing Tables 
The routines that follow allocate, initialize, and dispose of tables. 


ThlinitTable Initializes and formats the CellTable it receives as an 
argument. Every cell within the initialized CeliTable will 
be identical, with a uniform number of characters and lines 
ina field. 

TbhlDisposeTable Disposes pf the specified cell table pointers and 
descriptors. You can specify whether it should dispose of 
the values of the fields in the table or retain them. 

TblAddCol Appends another column to the CellTable matrix. The 
appended columns may have a different field width 
(characters per line) from the columns of the table being 
appended. 

Thi NewScreen Returns a pointer value to a screen array with the given 
number of columns, calCount. 

ThlDisposeScreen Deallocates screen arrays that have been created by 
TblNewScreen. The number of columns to be disposed of must 
equal the number of columns that were allocated when the 
screen array was created. 

Thi DisposeCol Deallocates column arrays that have been created by @ 
ThINewCol. The number of rows to be disposed of must equal 
the number that were allocated when the column array was 
created, 


Editing Tables 


The following routines are used to change the contents of a table and to allow 
movement af the field outline around the table. 


ThlEditTable This all-purpose table routine inserts characters at the 
current field location and cursor position, performs 
various key functions, and redraws both the display and 
the cursor. 

Tb] ChangeFields Given a table and a movement character, moves the field 
outline from cell to cell. (It moves the cursor, too, if 
the cursor actually was in the currentCell.) 


Specifying Celis 


The routines that follow simplify working with a cell or group of cells within 


g 
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a table. 


@ ThlSetCurrentCell Sets CellTable.currentCell to the given coluan and row of 
the celiTable, This routine will change the position of 
the cursor and the highlighted cell. The display will 
change only when another procedure redraws the table, 
. however, 

ThlFieldGflelild Converts a CellId into a FieldPtr reference, which makes 
table values easier to refer to and to change. It is 
useful when working with cell variables of type Cellld, 
such as currentCell. 

Tbh1FindBounds Calculates which cells lie within a rectangle that has been 
defined in the pixel coordinates of the display window. 
Given an area on the screen, it allows you to update only a 
portion of the table. 

ThiFieidO#Col Row Siven a column and and a row of a cell table, it returns 
the pointer to the field. 

ThlEqualCells Returns True if the given Cellld’s are equal. 

TblCeltQnScreen Returns whether the cell is within CellTable.visible, i.e., 
whether it is to be displayed. 


Drawing a Table 
The routines that follow are used to actually display tables. 


Application Note: To draw a newly initialized table, your application must 
call TblDrawTable (to draw the fields) and TblHilightTable (to draw the cursor 
and to outline the cursor’s cell), Later, ThlEditTable and TbiChangeFields 
will update and redisplay the table when the application modifies it; they 
redraw the table, the cursor, the cell outline, and the range selection (if 
any). 


ThlDrawTable Clears all fields from the screen and redisplays them with 
their current values, by calling FldDrawField for every field 
in the table. It overwrites the entire area defined by the 
visibleRect. 

Thi DrawGrid Draws a frame around the visibleRect and grid lines between the 
fields of a table, if table.frame, table.verticalGrid, and 
table. horizontalGrid are True. If a variable is False, 
ThlDrawGrid does not draw the graphics associated with it. It 
does not redraw the fields of the table. The frame and grid 
lines are one pixel wide. 

TblUpdateRect Updates the cells that lie within a rectangle defining a 
portion of the display window. Given an area on the screen, 
it allows you to update only a portion of the table. It is 
useful for redrawing the table after a message, a menu, or a 
form has been displayed. 

ThiSetVisible Adjusts table.visible and table.constraint so that they lie 
within the table.visibleRect clipping rectangle. The procedure 
adjusts the top, bottom, left, and right of table.constraint as 
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well, Constraint is based upon the number of entire cells that 
can fit within visibleRect. TbiSetVisible does not allow 
constraint to contain cells that appear only partially on the 
screen, This restriction ensures that the cursor and cell 
outiine can move inte entire cells only. 


INVERTING A TABLE 


The following routines are used to invert (display in reverse video) specified 
parts of a table. 


ThlInvertRange Inverts the current selection range, either a range of celis or 
a range of text within a single field. A range is a 
rectangular span of cells that has been selected by the user. 
Nothing will happen i# the procedure is called and no range has 
been selected. 

TblInvertSpan Given a span of cells, it inverts the displayed cel] of each 
field within the span. Spans are rectangular areas defined by 
column and row parameters. TblInvertSpan will invert the 
additional selections when a user scrolls during a selection. 


Highlighting a Table or Cell 


The following routines are used to invert and highlight specified parts of a 
table. 


NOTE: Call ThiHilightTable and Tb]UnhighlightTable whenever moving from a 
table to a menu and back or when moving back and forth between windows. 


ThlHilightTable Draws the cursor in the currentCell, inverts any selected 
range of cells, and highlights all cells in the table that 
require highlighting. 

TblUnhilightTable Given a cell table, it erases the cursor, uninverts any 
range of selected celis, and removes the highlighting from 
any highlighted celis. The cursor is erased graphically 
only, so you must reset it elsewhere with TblSetCursor. 

ThIHilightCell Given a CellTable and a Celild, it draws the appropriate 
outline around a cell, based on the value of hilightKind. 

Tb1DimHilightCell Draws a dashed outline around a cell. 


Beralling 

The table routines supports two types of scrolling, the easy case and the 
difficult case. The next version of this manual will provide up to date 
examples of how to program these two cases. 


TolScroll The easy case: It scrolls the view of the table in the 
direction indicated by ch (left arrow, right arrow, up 
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arrow, or down arrow), and updates the display. It also 
updates visible and constraint so that they match the 
displayed area. 

ThiGetSelectedCellids The difficult case: locates the movingCell and anchor 
Cellids, rearranges them in ascending order, adjusts 
them from relative “unscrolled" Cellids to absolute 
"scrolled" Cellids, and returns them as “first” and 
"last" absolute (logical!) coordinates, 

ThlScrollAdjustCellid The difficult cases transforms an "unscrolied" Cellld 
that is relative to the display screen into an absolute 
"scrolled" Cellld. 


Coordinating Text and Cell Selections 


The following routines are used in conjuntion with commands such as Move and 
Erase to simplify highlighting and confirmation of selected areas of a table. 


ToiStartSelection Puts the table into command mode and sets 
table.commandChar to ch. It works the same as if the ch 
tharacter had been included in the set of keys lin 
table.commands) passed to TblInitTable, and then 
ThlEditTable was called later with that character. In 
both cases, highlighting of selections is enabled. 

TblConfirmSelection Used to save the source selection range for commands that 
require two selection ranges, such as Nove and Duplicate. 

“ The table code will leave the source selection 
& highlighted while the user selects a destination range. 

TblEscapemode Puts the table into the normal (non-command) state, 
un-inverts any cell or text selection ranges, but leaves 
the cursor and the highlighted cell on. 
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CHAPTER 12. COMMON CODE PROCEDURES AND FUNCTIONS 


This chapter lists all of the procedures and functions provided by Common Code 
in alphabetical order. For discussions of concepts and interactions of these 
calls, refer to the appropriate chapter earlier in this manual. This chapter 
simply lists the calls in alphabetical order and provides a comprehensive 
description of each call for maximum ease-of-use for reference purposes. 
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AppendAnyChar 


PROCEDURE AppendAnyChar (VAR str: StringPtr; ch: Char); @ 


Purpose and Operation 
This procedure appends a single character to the tail of the string: 

str i= str + ch 
If the string would exceed its max length when the character was appended, 
then AppendAnyChar allocates a new string with a greater max length, copies 
str into it, and appends ch to it. {t disposes of the original str and sets 
str to the newly created string. 


AppendChar 


PROCEDURE AppendCharidest: StringPtr; chs Char)3 


Purpose and Operation 
This procedure appends a single character to the tail of the dest string: 
dest := dest + ch 
However, if the dest string would exceed its max length when the character "@ 
appended, then AppendChar will not append it, and it will not return an error 
message either. 
AppendString 
PROCEDURE AppendString(dest, source : StringPtr); 
Purpose and Operation 


AppendString concatenates the source string to the tail of the dest string, 
like so: 


dest := dest + source 
The source string remains unchanged. If the append operation would make dest 


too long (overflowing its max length), then the source string will be 
truncated to fit the available space, 
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AppendString 
PROCEDURE AppendString(dest, source : StringPtr); 
Purpose and Operation 


AppendString concatenates the source string to the tail of the dest string, 
like sa: 


dest := dest + source 
The source string remains unchanged, If the append operation would make dest 


too long (overflowing its max length), then the source string will be 
truncated to fit the available space. 
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AuthorOfThisFile 


FUNCTION AuthorOfThisFile(conn: Words 
VAR authorProductCode: Word; 
VAR versionO#ThisFile: Byte; 
VAR error: Integer ): AuthorType; 


Purpose and Operation 


Given the connection number of a file, this function, on return, provides the 
product code and version number from the file’s authorID record. The function 
also returns an indication of whether the file is in the new (3.0) format, old 
(2.0) format, or in neither format. 


Parameters 
authorProductCode The product code identifying the application that created 
this data file. 


versionDfThisFile A byte (from the authorID record) specifying compatibility 
level of the data file. 
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CadErase 


1) PROCEDURE CadErase {conn : Words 
msg i MessagePtr; 
VAR error : Word); 


Purpose and Operation 


This procedure displays the prompt "Confirm to erase file". If the user 
confirms the prompt, the routine erases the file specified by the connection 
number (conn) while displaying the message “Erasing file". When the file has 
been erased, the message "File erased" is displayed. If any key other than 
CODE-RETURN is pressed after the “Confirm to erase file" prompt, the message 
"No files erased” is displayed and no file is erased. 


Parameters 
conn The connection number of the file to be erased. 
msg A pointer to your message area. 


Procedures and Functions 12-5 


CadNediatitzsage 


PROCEDURE CmdMediaUsage (pathName : StringPtr; OS 
initialUsage ; LongInt; 
msg : pessagePtr; 
VAR refresh : Rectangle; 
VAR error +: Word); 


Purpose and Operation 
This procedure implements the Usase (CODE-U) command that is supported in all 


GRID applications. It displays the current usage of system memory and storage 
devices, and also the name of the current data file in the format shown below: 


Satur 
Hard Disk 

commoncede 
ConnandProcs 


168 Free 
408 Free 


QO 
of chat 


Parareters @ 


pathname The pathname of the current data file. 

initialUsage The Long Integer returned by MsgInitialUsage which indicates 
the initial RAN usage before the data file was loaded into 
memory. (MsgInitialUsage should be called when you are 
initializing your application.) 

asg A pointer to the your message area. 

refresh A Rectangle that, on return, indicates what portion of the 
screen needs to be updated by the application. 
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CmadProperties 


PROCEDURE CadProperties (pathName +: StringPtr; 
msg : MessagePtr; 
VAR refresh : Rectangle; 
VAR error : Word); 


Purpose and Operation 


This procedure displays the properties (characteristics) of the file specified 
by the pathname parameter. It should be called when the user has selected 
"Show ¢ile characteristics” from the Transfer menu and has specified the 
desired file by confirming the resultant File form. An example of the 
resultant display is shown below: 


Qevice Hard Disk 
Subject _cennoncede 
Title AboutThisBook 
Kind Text 


Version 0.0.0 
Lensth = 1728 
Created Tuesday 28-Feb-84 3:55 pn 
Modified Tuesday 28-Feb-8¢ 3:55 pn 


File Charac 


Paraseters 


pathname A pointer to the pathname of the file whose characteristics are to 
be displayed. 

msg & pointer to the your message area. 

refresh A Rectangle that, on return, indicates what portion of the screen 
needs to be updated by the application. 
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CompareBytas 


FUNCTION CompareBytes(VAR source!, source2: Bytes; 


count: Word; 
VAR index: Word): Boolean; 


Purpose and Operation 


Compares one memory area with another ane to see whether they match. They 
must be the same length. 


Paraseters 


source! 


source2 


count 


index 


Returns 


A pointer to the first location of the data. 
A pointer to the second location of the data. 


The number of bytes to compare. This routine compares bytes in 
source! to an equal number of bytes in source2. 


@n index into the source's memory area, it indicates the first 
position in the first memory area where the two memory areas did 
NOT match. If the two memory areas are identical, then index = 
FFFF, This value is returned by reference. 


NOTE: the index starts at 0 (not 1) in order ta be compatible 
with PL/M. Hence, index = 0 represents the first position in 
the memory area. 


CompareBytes returns a Boolean indicating whether or not the two memory areas 


matched. 


If CompareBytes returns True, then the two areas matched exactly. 


If CompareBytes returns False, then the index variable contains the first 
character position where the two areas did not match (all character positions 
before it did match). 
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CompareStrings 
® FUNCTION CompareStrings(stri,str2: StringPtr): Comparison; 


Purpose and Qperation 


The function compares the ASCII values of two strings character by character, 
from left to right. Thus the greater string will be the one containing the 
first character with a higher ASCII value. If two strings match up exactly 
except that one string has additional characters, then the string with the 
extra characters will be the greater one. 


NOTE: This routine does NOT discriminate between uppercase and lowercase. The 
string ‘a red cat ran’ is greater tnon ‘A Red Cat’. 
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ConcatLits 


FUNCTION ConcatLits(VAR liti, 1it2: Bytes): StringPtrs @ 


Purpose and Operation 
The function will create a new string with the literals lit1 and 1it2 


concatenated together. It allows you to concatenate string constants. The 


len and max of the created string is the su of the lengths of the two 
literals. 


Example 


CONST x = ‘In progress ‘3 
MsgString := ConcatLits(‘Find: ‘, x); 


MsgString*chars now equals ‘Find: In progress’ 


ConcatStrings 


FUNCTION ConcatStrings(stri,str2:StringPtr): StringPtr; 


Purpose and Operation @ 


The function will create a new string containing stri and str2 concatenated 
together. The len and max of the created string is the sum of the current 
lengths of the two strings (not the sum of their max lengths). It disposes of 
stri and str2 after creating the new string. 
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CopyOrstring 
© FUNCTION Copy0fString{str: StringPtr): StringPtr; 
Purpose and Operation 


This function creates a new string and copies the value of str to it. The len 
and max of the new string are both equal to the len of str. 


NOTE: some Common Code routines deallocate the strings they receive as 


arguments. If you don’t want to have certain strings deallocated by then, 
make a copy of the string with this procedure. 


CopyString 
PROCEDURE CopyString{source, dest: StringPtr); 
Purpose and Operation 
This procedure copies the value of the source string to the dest string. Both 


source and dest must be allocated already. If the source string is longer 
than the dest string, then any extra characters will be truncated. 
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DataForaConfirmed 


dataFormMode : DataForaModeType; 
msgStatus : MessagePtr; 
msg : StringPtr; 
VAR rect : Rectangle; 
keyProcess : WORD; 
VAR ch : CHAR) : BOOLEAN; 


FUNCTION DataFormConfirmed (VAR dataForm : DataFormType; a 


Purpose and Qperation 


This function displays the specitied form and, when confirmed, returns with 
the choices the user selected for each item on the form. The function handles 
display of the form and responds to arrow keys to move the selection outline 
from choice to choice, The appearance of the form, definition of item types, 
and the choices that will be displayed must be defined in a PLM data 
structure. Refer to Chapter @ for a description of the PLM data structure and 
the data types used with the forn. 


Paraneters 


dataForm The form's PLM data structure. 
dataForaMode This is an enumerated types "normalDataForm" initializes and 
displays the form, "“initOnlyDataForm" just initializes the form, 
“runOnlyDataForm” displays an initialized form. @ 
msgStatus The MessagePtr you use for all activity with messages. If any 7 
messages are currently visible then the form will be displayed 
above them, 
msg A pointer to the string to be displayed as the prompt for the 
form. If some messages are already displayed this one will be 
stacked upon the others. Passing “NIL” for this parameter causes 
no additional messages to be displayed. This stringPtr is 
automatically deallocated. 


Note: This string is actually displayed as a prompt. You must 
call MsgClearPrompt to remove it. 

rect This rectangle defines what part of your window the form will be 
displayed in. Common Code will update this rectangle to reflect 
what part of the window was actually used. It will not include 
the area used by any messages. 

keyProcess This is the cursor process ID. Common Code requires this for 
menus, forms, and tables. [It must be initialized with 
"FieldStartKeys” prior to use, 

ch This CHAR returns the key that was pressed Jast. You should look 
at this value only if the form was not confirmed. 
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DataMenuConfirmed 


© FUNCTION DataNenuConfirmed (dataMenu : DataNenuType; 
msgStatus ; MessagePtr; 
msg : StringPtr; 

VAR rect : Rectangle; 
keyProcess : WORD; 

VAR selection : INTEGER; 

YAR ch : CHAR) : BOOLEAN; 


Parameters 

dataMenu The menu (the name of the second data item defined in the PLM 
module). 

asgStatus The MessagePtr you use for al] activity with messages. If any 


messages are currently visible then the menu will be displayed 
above thea. 

msg A pointer to the string to be displayed as the prompt for the 
menu. If some messages are already displayed this one will be 
stacked upon the others. Passing "NIL" for this parameter causes 
no additional messages to be displayed. This stringPtr is 
automatically deallocated, 
Note: This string is actually displayed as a prompt. You must 
call MsgClearPrompt to remove it. 

rect This rectangle defines what part of your window the menu will be 
displayed in. Common Code will update this rectangle to reflect 
what part of the window was actually used. It will not include 
the area used by any messages. 

keyProcess This is the cursor process ID. Common Code requires this for 
menus, forms, and tables. It must be initialized with 
"FieldStartKeys" prior to use. 

selection This Integer returns which item was selected on the menu. 

ch This CHAR returns the key that was pressed last. You should look 
at this value only if the menu was not confirmed. 
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DeleteBytes 
PROCEDURE DeleteBytes (VAR source, dest: Bytes; 
sourceLen, pos, byteCounts Word); 
Purpose and Operation 
This procedure deletes a given number of bytes from an area of memory; the 
remaining bytes are moved together to close up the resulting gap. This 
procedure is useful for removing elements from arrays, structures, strings, 


etc. 


Source and dest can refer to the same area of memory or to different areas. 


Parameters 

source A pointer to an area of memory. DeleteBytes copies source into 
dest, removing a specified number of bytes, as shown below. 

dest A pointer to the resulting area of memory that contains the source 


area without the deleted bytes. 
sourceLen The length of the source area, in bytes. 


pos The position within the source area where DeleteBytes begins 
deleting bytes. 


byteCount The number of bytes to be deleted. g 


DeleteFronmString 
PROCEDURE DeleteFromString(str: StringPtry 
firstPos, lastPos: Integer); 
Purpose and Operation 
This procedure deletes characters from the string, starting at firstPos and 


ending at lastPos. The routine then joins the remaining characters together 
to close the gap. The max value of the string is unchanged. 
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EqualiStrings 


FUNCTION EqualStrings(stri,str2: StringPtr): Boolean; 
Purpose and Operation 


The routine compares two strings character by character and returns True if 
they have the same characters and the same number of characters. 


NOTE: This routine does NOT discriminate between uppercase and Jowercase. The 
string ‘GRID’ is equal to ‘grid’. 


ExactCopyorstring 


FUNCTION ExactCopyOfString (oldStr +: StringPtr) : StringPtr; 

Purpose and Operation 

This function makes an exact copy of a specified string and returns a 
stringPtr to the copy. The exact copy will have .len set to the current .len 
(as opposed to .max) of the specified string. This function is often used in 
conjunction with data driven forms to obtain a copy of editable string choices 
which would otherwise be when the form is disposed of. 

Parameters 

oldStr A pointer to the string that is to be copied. 

Function Return 


A pointer to the new string created by the copy operation. 
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FFExecuteCommand 
FUNCTION FFExecuteCommand (filename: StringPtr) : WORD; 
Purpose and Operation 


When the File form is confirmed and the user has specified a “Next action” of 
"Get new file and its application”, the function FFExecuteCommand is used to 
get the new application and file. This function requires only the file name 
(as returned by the FileForaConfirmed function) as its input. It passes this 
file name to the system Executive which retrieves the appropriate application 
to work with that file. For example, if you pass a file name with a Kind of 
“Text” to FFExecuteCommand, the Executive looks for an application program 
with a Kind of “Run Text* and loads that program and the specified text file 
into memory. 


The calling program must check for an error return of “ok" from the function 

and then do an OsExit. The system Executive will not load the new application 

program and the specified file into memory until the current process has 

exited. 

Parameters 

fileName A string pointer to the name of the file as returned by the 
FileFormConfirmed function. 

Function Return 

The function will return an error such as “File not found" if it cannot locate 


an application that matches the specified file's kind. If an appropriate 
application is found, the function returns “ok”. 
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FileFormConfirmed 


a) FUNCTION FileForaConfirmed (FFMode: FFModeType; 
userPID: WORD; 
VAR ch: CHAR; 
VAR formRect: Rectangle; 
prompt: StringPtr; 
VAR pathName: StringPtr; 
spare: StringPtr; 
VAR defaultRec: FFDefaultTypeRec; 
attachMode: BOOLEAN; 
mode :BYTE; 
access: BYTE; 
VAR connection: WORD; 
ExchangeMode: FFExchangeMode; 
VAR ExchangeResult: FFExchangeResult; 
VAR SaveResult: FFSaveResult) : Boolean; 


Purpose and Operation 


This function displays the File form, handles movement of the selection 
outline when the user presses the arrow keys, and returns with the selected 
items when the form is confirmed. The function also displays appropriate 
messages and prompts. The items that will be displayed in the form can be 
varied according to conditions established when the function is called. For a 
thorough discussion of the capabilities of this function, refer to Chapter a. 


Parameters 

FFMode An FFGet or FFPut. Usually set to FFGet except for “Write to a 
file’. Determines which message will be displayed with the 
form, 

userPID The process ID of your keyboard process. Used by the function 
to read keystrokes. 

ch The last keystroke typed. You should need to look at this 
character only when the form is not confirmed. 

foraRect This rectangle detines what part of your window the form will 
be displayed in. Returns the rectangle that your application 
should refresh. 

prompt A pointer to the string to be displayed as the prompt for 
the form, This stringPtr is automatically deallocated. 

pathNawe The pathName parts that the function should display if defaults 
are specified in the defaultRec. On return, it indicates the 
actual pathName that the user confirmed. 

Spare Not currently used. Pass NIL to this parameter to enusre 
compatibility with future uses, 

defaultRec Defines which part(s) of the pathName parameter should be 


displayed initially in the form and which parts should be 
initially blank. 

attachMode Species whether the indicated file should be attached. You'll 
usually want to attach the file except for such operations as 


®@ 
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"Show file characteristics". 


fileMode The file mode for the attach such as update, old, new. (See 
OsAttach in the GRiD-OS Reference for a discussion of these 
oodes,} @ 
access The access mode for the attach such as read only, write only, 


update (read/write). (See OsAttach in the GRiD-OS Reference 
for a discussion of these modes.) 

connection The connection number of the attached file returned by the 
function. 

exchangeMode Specifies whether to display the "Next action" (exchange) 
and/or "Save changes” items on the form. 

ExchangeResult On entry, speciifies which of the "Next action” choices should 
be in the selection outline, on return contains the choice that 
was confirmed. 

SaveResult On entry, specifies which of the “Save changes" choices should 
be in the selection outline, on return contains the choice that 
was confirmed. 
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FinalizePropertiestength 


PROCEDURE FinalizePropertiesLength(conn: Word; 
VAR error: Integer); 


Purpose and Operation 


This procedure takes the current File Position (LongInt) and writes that value 
to the file‘s header when the file is written to a device. The procedure does 
not, itsel#, know the length of common properties. You should call this 
procedure immediately after you have written the last of your common 
properties records. After calling this procedure, you can begin writing data 
records and application properties records. 


Paraneters 


conn The connection number specifying the data file whose properties 
records length are being finalized. 
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FindByte 


FUNCTION FindByte(VAR source: Bytes; 
ByteToFind: Char; ( | 


counts Word; 
VAR index: Word): Boolean; 


Purpose and Operation 


This function searches an array of bytes in memory for a given character, and 
returns its position in the array. 


Paraaeters 
source 
ByteToFind 
count 


index 


Returns 


A pointer to the location of the data to be examined. 

The character or byte to be compared with the memory area. 

The length of the memory area, in bytes. 

An index into the source’s memory area, it indicates the 
position in the area where the memory and the character matched. 


This value is returned by reference. 


NOTE: the index starts at 0 (not 1) in order to be compatible 
with PL/M, Hence, index = 0 represents the first position in 


the memory area. 


FindByte returns a Boolean indicating whether or not the byte mas found in the 


memory area. 


If FindByte returns True, then the index variable contains the 


character position where the aatch was successful. 
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FidDimHilightFieid 


2) PROCEDURE FldDimHilightField(VAR field: FieldDescriptor); 


Purpose and Operation 


This procedure draws a one-pixel dashed outline box around the field, leaving 
a one-pixel space from the field boundary. 


FidDrawCursor 


PROCEDURE FidDrawCursor (VAR cur: CursorDescriptor); 


Purpose and Operation 


This procedure makes the cursor visible and sets cur.on to True. It also sets 
the cursor blink count. 


Procedures and Functions 12-21 


FidDrawField 
PROCEDURE FldDrawField(VAR field: FieldDescriptor)y S 
Purpose and Operation 


This procedure erases the given field and then redisplays the field's text 
string. It clips the cursor and text to the field’s rectangle -- when the 
field is full, any extra characters don’t overwrite the adjacent celis. Cali 
it when you need to display initial values or redraw the updated value of a 
single field. This procedure accomodates multi-line fields with 
word-wrapping, but does not word wrap the last line of the field. 


lf the fieldKind is numeric, then the field receives additional formatting. 
If a number is too wide to fit in the field's display area, then FidDrawField 
truncates any additional fractional digits without rounding. If the integer 
portion of the number is too large, then it displays asterisks in the field to 
indicate overflow. The actual contents of the field are not changed, however. 


FidDrawFieidChars 


PROCEDURE FldDrawFieldChars(VAR field: FieldDescriptor)} 


Purpose and Operation 


Draws the field's text string without erasing the field first. It chips the 7 
cursor and text to the field's rectangle -- when the field is full, any extra @ 
characters don't overwrite the adjacent cells. This procedure accomodates 
multi-line fields with word-wrapping, but does not word wrap the last line of 

the field. 


If you're redrawing many fields at once, it’s faster to erase many fields at 
the same time, instead of erasing them individually, as FldDrawField does. 
The faster way is to erase with WinEraseWindow or WinEraseRectangie, and then 
redraw the fields with FidDrawFieldChars. 
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FidEditField 


FUNCTION FIdEditField(VAR cur; CursorDescriptor; 
chs Word): FieldEditResult; 


Purpose and Operation 


This all-purpose routine inserts values into the field's character string, 
performs various key functions, and updates both the display and the cursor. 
It recognizes BACKSPACE, CODE-BACKSPACE (erase previous word), 
SHIFT-CarriageReturn, and arrow keys. Pressing the RETURN key enters both a 
Carriage Return (CR) and Line Feed (LF). To enter only a CR, press CTRL-M. 


Returns 


After attempting to insert a character or perform a function, the procedure 
returns one of these values: (See Caution below.) 


ok The procedure successfully processed a character, such as an 
arrow key, but did not change the contents af the field. 


processed The procedure processed a character that changed the field‘s 
contents. This includes inserting, modifying, or deleting text 
characters in the field. 


escaped The user pressed ESC, and nothing was done to the contents of 
the field. 
ignored The procedure received a character that it did not know how to 


Process. By testing for this result, you returns bufferFull. 
That is, if no text string has been allocated for a field, then 
that field's text buffer cannot accept text and therefore will 
appear to be full. 


fieldFull Though the text string has room for @ore characters, the 
additional character would have been displayed outside the field 
boundaries. This result restricts fieids to their own 
boundaries, and prevents them from overwriting other fields. 


If you want to pass a character of type Char to this routine, use the 
following example code. in the example, cursor is of type CursorDescriptor, 
oneCh is of type Char, and result is of type FieldEditResult: 

result := FldE&ditField(cursor, Ord{oneCh)); 
If the user types a nusber that is too large to fit in a numeric field, the 
field now fills up with asterisks. Erasing part of the number or enlarging 


the field causes the asterisks to disappear. 


The FieldEditResult of fieldFull can now be used to support multiline fields. 
The fieldFull result means that there was enough room in the field's text 
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buffer to hold the new character, but not ail the characters in the field can 

be displayed. (The character is inserted into the field anyway. The 

characters that are not shown are at the end of the buffer.) To display the 

hidden characters by changing the field into a multiline field, the program @ 
can change the size of the field’s box and redraw it. 


There are two ways to generate a fieldFul] result. 


o Fill up the field with text. The first character that cannot be 
displayed will cause a fieldFull result. 


o Type SHIFT-RETURN on the last line of a field. After inserting the 
GHIFT-RETURN character into the field, FieldEditField returns 
fieldFull. 


By checking for the fieldFull condition, the application program can then add 
another line of vertical space to the field. To add space to a single field, 
change the size of its box and redraw it. 


Pressing the RETURN key by itself only inserts a Carriage Return ~ Line Feed 
pair into the field. You must press SHIFT-RETURN to begin a new line of a 
field. This distinction is necessary to maintain compatability with Compass 
Computer interchange files. SHIFT-RETURN enables you to define multiple lines 
in a field, which can then be combined as a single Compass file record. 


CAUTION 
FldEditField currently does not produce a FieldEditResult of “processed"; 
it returns the "ok" result under the conditions described for "ok" and 
“processed”, It currently does not produce a FieldEditResult of @ 
"escaped"; it returns the "ignored" result under the conditions described } 
for “ignored” and “escaped”. (The “processed” and “escaped” values are 
still legal values for FieldEditResult. They are not currently returned 
as values.) 
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FidEraseCursor 


) PROCEDURE FldEraseCursor (VAR cur: CursorDescriptor); 


Purpose and Operation 


This procedure erases the cursor from the display without affecting its 
position in the field or in the window coordinates, and sets the blink count. 


S) 
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FidFormatLline 


FUNCTION FidFormatLine (VAR field: FieldDescriptory 
charindex: Word; 
VAR JiaPos: Word; 
VAR leftEdge: Integer): Boolean; 


Purpose and Operation 


FidFormatLine examines the text of a FieldDescriptor and determines where the 
text should appear on each line of a multi-line field. It does not display 
the field, however. 


It performs word-wrapping automatically: if a word is too long to fit on a 
line, FidFormatLine does not include it in that line. The last line of the 
field is not word-wrapped, however. Note that all characters in a field are 
displayed, including spaces. If a space occurs in the field, it may be 
displayed as the first character of a line; that line will appear indented by 
a space. 


This function, also interprets RETURN and SHIFT-RETURN separately. 
FldFormatLine formats Carriage Return and Line Feed characters just as it does 
any other characters, by inserting them into the line. I¢ FldFormatLine 
encounters a SHIFT-RETURN character when formatting the line, it ends the line 
with that character. 


Paraneters 
Tt takes these parameter variables: 
field The FieldDescriptor of the field being formatted. 


charIndex fin index into the field‘s text string. It shows which character 
in the text string will become the first character of a line in 
the field. For example, if you call FldFormatLine three times 
with charIndex = 1, 6, and 11, then the three formatted lines in 
the field would begin with the first, sixth, and eleventh 
characters respectively from the text string. 


limPos An index into the field’s text string that shows which character 
in the text string will begin the NEXT line. This variable is an 
OUTPUT from FldFormatLine. 


leftEdge The position of the left edge of the text, measured in pixels 
from the left boundary of the window. In conjunction with 


FieldDescriptor.box, it controls the alignment of text within the 
cell. 


Returns 
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The output of FldFormatline is a Boolean. IJ# it is True, then the current 
formatted line contains the last of the text from the text string. If it is 
False, then there is still more text left in the text string to be formatted. 


Example 

To format a multi-line field, the application will need to call FldFormatLine 
repeatedly. The limPos that FldFormatLine calculates becomes the new 
charIndex when FidFormatLine is called again: 


FidForaatlLine { , charIndex, limPos, } 
ai 


FidFormatLine { , charindex, limPos, )} 


FidFormatLine ¢ , charindex, limPos, } 
The liPos variable is an output representing where the next line should 


start. When you call the procedure again, the old limPos should now become 
charIndex, which shows where the current line begins. 
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FidHilightFielid 


PROCEDURE FIdHilightField(VAR field: FieldDescriptor); 8 


Purpose and Operation 

This procedure draws an outline box around the field. The line of the box's 
outline is three pixels wide, and it lies one pixel away from the field's 
puter boundary. The cursor’s three-pixel outline is generated automatically, 


FidiInsertinFielid 


FUNCTION FidInsertInField(VAR curs CursorDescriptor; 
ch: Char): Boolean; 


Purpose and Operation 
This function inserts a character in the field at the cursor's current 
character position, and verifies its insertian by returning True or False. It 
does not redraw the display on the screen, Most applications should call 
FldéditField instead. 
FidinvertChar 
PROCEDURE FldInvertChar (field: FieldPtr; pos: Word); 
<i 
Purpose and Operation © 


This routine performs an exclusive OR operation with a field’s screen display 
to change a character position to inverse-video. 
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FidReadKey 


FUNCTION FidReadKey(VAR cursor: CursorDescriptor): Word; 


FidReadkey replaces two routines, ConKeyPressed and ConCharIn, that were used 
to busy-wait for input from the keyboard. Instead, this procedure leaves the 
processor free for other tasks while waiting for a key to be pressed, 


The function waits for an interrupt signifying that a key has been pressed. 
If no keys are pressed for a certain time interval, the function blinks the 
cursor, and then resumes waiting for a key to be pressed. (Your application 
program will wait at the statement containing this function call.) If a key 
is pressed, then the function returns the character, and your application 
program can continue. 


Note: Call FldStartKeys once when you initialize your program, before calling 
this function. When your program finishes, call OsDeleteProcess to delete the 
cursor process. 


Status bits from the keyboard are returned in the high order byte of the word. 
The high-order byte of the word is defined as follows: 


Bit Abbreviation Meaning 
8 IBF =1 if character available 
9 OBF sl if latest command 

has not been processed 
10 (not used) {not used) 
W (not used) (not used) 
12 RPT =1 if a repeated character 
13 SHFT =1 if a shifted character 
14 CODE =1 if a code character 
15 CFRL =1 if a control character 


Use the example code below to ignore the status byte in your programs. In it, 
ch is of type Char, and cursor is of type CursorBescriptor. 


ch 3= Chr (FldReadKey(cursor)); 
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FidsetCurser 


PROCEDURE FidSetCursor (VAR cur: CursorDescriptor} 
field: FieldPtr); e 
Purpose and Operation 


This procedure sets the cursor to the given field, at the last character 
position and sets Cur.on to False. The procedure does not alter the display. 


FidsetPos 
PROCEDURE FldSetPos(VAR cur: CursorDescriptor; pos: Integer); 
Purpose and Operation 
Given the character position of the cursor, it sets the x-y pixel coordinate 
for the place element of the cursor. An application can set the cursor to any 


character position in the field. The display is unchanged. Cur.on is set to 
False. 


FldStartKeys 


PROCEDURE FldStartKeys (VAR cursor: CursorDescriptor)y 


FidStartKeys starts a process to control the cursor. It puts the PID of the S 
process into cursor.keyProcess. (You use it to “initialize” the cursor, in 
effect.) 
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FontCount 


@ FUNCTION FontCount: Integer; 


Purpose and Operation 


This function returns an integer which indicates how many fonts are available 
in the system. Most applications will not need to use this function since, if 
they have the name of a font, they can directly obtain the index number of 
that font and need not scan through the list of fonts. However, if an 
application (for example GRiDManager} needs to maintain its own list of fonts, 
FontCount may be useful. 


FontGetN 
FUNCTIGN FontGetN (names StringPtr): Integer; 
Purpose and Operation 
Given a pointer to the font name, this function returns an integer (index) 
that is associated with the current font. This value can then be used to 


correctly position the choice field highlight when an application dispiays a 
data driven fora. 


FontNthName 
FUNCTION FontNthName(index: Integer): StringPtr; 
Purpose and Operation 


Given the font index number, this function returns a pointer to the string 
containing the name of a font. (If the index value is not in the list of 
fonts, the function returns NIL.) This function can thus be used by an 
application to obtain the name of the current font associated with a data 
file. The application could then, for example, write the name of that font to 
the common properties record of the file. 
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FontSetNare 


PROCEDURE FontSetName(name: StringPtr; VAR error: Word); 
Purpose and Operation 


This procedure causes the font specified by the name parameter to be loaded 
into memory. This font thus becomes the current font. 


Possible Errors 


All disk errors. 
Out of memory. 


FontSetNth 
PROCEDURE FontSetNth(index: Integer; VAR error: Word) 
Purpose and Operation 


This procedure causes the font specified by the index parameter to be loaded 
into memory. This font thus becomes the current font. 


Possible Errors 


All disk errors. & 
Out of memory. 
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FreeString 


PROCEDURE FreeString(VAR str: StringPtr)s 
Purpose and Operation 


Given the StringPtr to a string, FreeString will release the memory that the 
string occupied and return that memory to the PASCAL heap. 


Note: you must NEVER modify String*.max, because FreeString uses that number 
to determine how much memory to release to the heap. Other data values aay be 
incorrectly released if String*.max is changed from its original value. 


FreeStringsiInDataForm 


PROCEDURE FreeStringsInDataForm (VAR dataForm : DataFormType); 


Purpose and Operation 
This procedure frees all the strings in a data form. It should be used only 
if you do NOT store the values of a form in the form itself. If you store the 


values of a form in permanent variables, you can call this procedure after you 
have copied current form values into the variables. 


Parameters 


dataForm The form whose strings are to be freed. 
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GetNextRecord 


FUNCTION GetNextRecord (conn: Word; 
VAR gRecord: GeneralRecordPointer; | 
VAR gRecordLength: Word; 
thisIsTheAuthorCalling: Boolean, 
+ VAR errors Integer): Boolean; 


Purpose and Operation 


Given a file’s connection number, this function returns with a pointer to the 
next record from the data file and the length of that record. If you have 
specified that you are the author of this file, all records, including 
application (private) properties, will be retrieved using this call. If you 
have specified that you are not the author, application properties records are 
automatically skipped and only common properties records and data records will 
be retrieved. The procedure updates the current file position pointer so that 
it is pointing just beyound the end of the record just returned. 


Parameters 

conn The connection number for the file whose records are 
being read. 

gRecord A pointer to the beginning of the next record from 


the data file. The procedure allocates a new record 
if gRecord is NIL or if the current jength of the 
record is shorter than the next record in the file. 
{The format of GeneralRecord is shown below.) 

thisIsTheAuthorCalling A Boolean that, if set true, permits all records in 
the data file to be read. If set false, the 
function automatically skips application properties 
records and returns only comaon properties records 
and data records. 


GeneralRecord = RECORD 

headerByte: Bytes 

CASE Integer OF 
OFFh: ( textStrings ARRAY [1..2) OF Char }; { ends with CRLF } 
OFEh: ( commonPropss CommonPropertiesRecord ); 
OFDh: ( userLength: Word; userProps: ARRAY [1..13 OF Byte )3 
000h: ¢ length: Word; binaryProps: Byte) 

END; 


GeneralRecordPointer = *GeneralRecord; 

Function Return 

The procedure returns a Boolean that is True if the first byte of the record 
contains FE hex (a common properties record) or FD hex tan applications 
properties record). The Boolean will be True for application properties 


records only if you are the author of the file (thisisTheAuthorCalling set 
True). 
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GetVersionString 


FUNCTION GetVersionString ({pID : Word) + StringPtr; 
Purpose and Operation 


This function returns a pointer to the string containing the version nuaber 
and message for the file identified by the pID parameter. GRiD applications 
use this function to obtain their own version number for display when the 
application is first initialized and when the user presses CODE-?. 


Parameters 

pip process ID for the current application. (Use OsWhoAml to obtain your 
own pID.) 

Returns 


A pointer to a string containing a three numeral version nuaber in the 
following format: 


“Version x.y.z° 

where x, y; and z are integers in the range [0..255]. Applications may assign 
Significance to x, y, and z. If the software has not had the version set in 
the file descriptor by the version program, the string returned will be: 


"Version 0.0.0° 
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InsertByteas 
PROCEDURE InsertBytes (VAR source, dest: Bytes; 
Ten, pos, byteCount: Word); 
Purpose and Operation 
This procedure inserts bytes into a specified area of memory. The contents of 
the inserted bytes are undefined. This procedure is useful for inserting new 


elements into arrays, structures, strings, etc. 


Source and dest can refer ta the same area of memory or to different areas. 


Paraneters 


source A pointer to an area of memory. InsertBytes copies source into 
dest, inserting a specified number of bytes, as shown below. 


dest A pointer to the resulting area of memory containing the source 
area and the inserted bytes. 


ten The length of the source area, in bytes. 
pos The position within the source area where the insertion begins. 


byteCount The number of bytes to be inserted. 
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InsertCharinString 
© FUNCTION InsertCharInString(ch: Char; 
S str: StringPtr; 
pos: Integer): Boolean; 
Purpose and Operation 


This function inserts a single character into a string. It inserts ch into 
str beginning at the character position given by pos, 


If inserting the ch would make str longer than its max length, then 
InsertInString returns False, and nothing is inserted. 
InsertiIinString 


FUNCTION InsertinString(piece, str: StringPtr3; 
pos: Integer): Boolean; 


Purpose and Operation 
This function inserts a string into another string. It inserts piece into str 
beginning at the character position given by pos. The existing characters of 


str are moved aside to make room for the insertion. 


If inserting the piece would make str longer than its max length, then 
InsertinString returns False, and nothing is inserted. 


IntegerToeString 
FUNCTION IntegerToString(ints Integer): StringPtr; 
Purpose and Operation 


IntegerToString converts an integer between -32748 and 327467 inclusive into a 
string, then returns a stringPtr to the string value. 
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MNoveBytes 


PROCEDURE MoveBytes(VAR source: Bytes; 
VAR dest: Bytes; length: Word); 


Purpose and Operation 


MoveBytes aoves data from one location in memory to another. 


Parameters 


source A pointer to the location of the data to be moved (i.e., to the 
first element of an array of bytes). 


dest A pointer to the new destination of the moved data {i.e., to an 
element of an array of bytes). 


length Specifies how many bytes are to be moved, from 0 to 65535. 


MaveReverseBytes 


PROCEDURE MoveReverseBytes{VAR source: Bytes; 
VAR dest: Bytes; length: Word); 


Purpose and Operation 

MoveReverseBytes moves data from one location in memory to another. It moves 
the data starting from the end of the data rather than the beginning, as shown 
in the figure below. This allows you to move bytes into a destination that 
overlaps the source location. 

Parameters 


source A pointer to the location of the data to be aoved (i.e., to the 
first element of an array of bytes). 


dest A pointer to the new destination of the aoved data (i.e., to an 
element of an array of bytes). {Note that this is the first element 
of the destination, not the last.) 


length Specifies how many bytes are to be moved, from 0 ta 45535. 
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N#sqCleartessage 
FUNCTION MsgClearMessage(msg : MessagePtr) : Boolean 
Purpose and Operation 


Erases any messages currently displayed. This does not erase prompts. 
Visible prompts are not affected by this function. 


If the return value of the function is true, the application must update the 
rectangle in the window indicated by asg*.rect, 

H#sgClearPrompt 
FUNCTION MsgClearPrompt{msg : MessagePtr) : Boolean 

Purpose and Operation 


Erases any prompts currently displayed. Messages that have prompts stacked on 


them are also erased by this function, otherwise messages are not affected by 
this function. 


If the return value of the function is true, the application must update the 
rectangle in the window indicated by asg*.rect. 
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MsgExit 
PROCEDURE MsgExit(code +: Word; msg : MessagePtr} 
Purpose and Operation 


This function is used before exiting an application. The code parameter will 
dictate which message wil] be displayed: 


code Message 
0 Retrieving subjects: In progress 
2 Gut of memory 


Confirm to exit 
other System Error: ferror coded 
Confirm to reinitialize system 


If the system is ready to continue (code 0 or 2), MsgExit will call OsExit(0), 
otherwise it will reboot. Note that this procedure is actually a combination 
of message and prompts according to the guidelines layed down in Chapter 6. 
Code 0 simply displays a message and exits, ignoring anything the user may do 
at the keyboard. Codes 2 will automatically exit on CONFIRM but should 
remain in the application if any other key is pressed. Any “other” code 
indicates a catastrophic event and the exit will be performed on CONFIRM; any 
other key might leave the user in the application ~- GRiD applications, 
however, typically exit regardless of what key is pressed at this point. 
(Here's your hat. There‘’s the door.) 
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KRaegiInit 
FUNCTION Msginit : MessagePtr 


Purpose and Operation 


This function dynamically allocates a MessageStatus record and returns a 


pointer to it. 4#ll necessary 
the location of the message. 


fields of the record are initialized, including 
The box field in type FieldDescriptor is 


initialized to the bottom of the current window. 


This is the default position 


of all single message/prompts and the point at which stacking begins. 


Each message or prompt you use aust have a MessageStatus record. Therefore 
you must call this function before calling the functions which actually 
display the message or prompt. 


The organization of the MessageStatus record is as follows: 


TYPE MessageStatus = 
RECORD 
messageShowing: Boolean; 
stackSize : Byte; 
field: FieldPtr; 
rect: Rectangle; {area to be updated} 
anythingShowing : Boolean; 
END; 


MessagePtr = “MessageStatus; 


A boolean that indicates if a message is currently 

displayed. If a prompt is showing, or if no message is 

showing, it is false. This field is NOT altered by the 

application. It is initialized by MsgInit and updated by 

the various message calls. 

Indicates the number of messages/prompts currently showing. 

This is NOT altered by the application. It is initialized 

by Msginit and updated by the various message calls. 

field Pointer to the field descriptor record containing the text 
and location of the message. 

rect The rectangle that the application should update if the 
boolean result of one of the message FUNCTION calls is true. 
This value is initialized by MsgInit, updated by the various 
message calls, and read by the applications. It is not 
altered by the applications, 

anythingShowing Boolean field that is not used in the current version of the 

Common Code message module, 


messageShowing 


stackSize 


The organization of the field descriptor record pointed to by the field 
Parameter is as follows: 


FieldDescriptor = RECORD 
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box: Rectangle; 

text: StringPtr; 

kind: FieldKind; 
END; 


FieldPtr = *Fielddescriptor; 


FieldDescriptor = 
RECORD 
box: Rectangle; 
text: StringPtr; 
kind: FieidKind; 
END; 


FieldPtr = “FieldDescriptor; 
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Nsginitialutsage 
FUNCTION MsginitialUsage: LongInt; 
Purpose and Operation 


When initializing -your application, call MsgInitialUsage to find the amount of 
memory taken by the application code itself, without the user's workspace. 


Hs@g@ShourDecoded 
FUNCTION MsgShowDecoded(msg + MessagePtr3; errorCode : Integer) + Boolean 
Purpose and Operation 
MsgShowDecoded takes an integer corresponding to an error message defined by 
the GRiD Operating System. It finds the text message corresponding to the 
error code, and displays it as a one line message. It erases any previous 
messages or prompts. It freezes the keyboard for two seconds, ignoring any 
input during that tine. 


Tf the return value of the function is true, the application must update the 
rectangle in the window indicated by esg*.rect. 


For a ist of error codes and their corresponding messages, See Appendix B of 
the GRiD-OS Reference Manual. 
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MsgShowError 
FUNCTION MsgShowErrorinsg : MessagePtr; str : StringPtr} : Boolean 

Purpose and Operation 
This function erases the previous message or prompt (stack), then displays the 
given string as a one line message at the bottom of the window. Unlike the 
other display routines, it freezes the keyboard input for two seconds. Any 
characters entered during this period are ignored. The asg variable keeps 
track of the status of the message. NzoShowError disposes of the strimg it 


receives as input. 


Tf the return value of the function is true, the application must update the 
rectangle in the window indicated by asg*-rect. 


Parameters 


msg A pointer to the MessageStatus record for this message. 
str A pointer to the message text that is to be displayed. 


Function Return 


46 boolean that, if true, indicates that the application must update the 
rectangle in the window indicated by psg*.rect. 
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N#sgShoutessage 
FUNCTION MsgShowMessage(msg ; MessagePtr; str ; StringPtr) +: Boolean 
Purpose and Operation 


This function erases the previous message or prompt stack before displaying 
the given string as a one line prompt at the bottom of the window. The asg 
variable keeps track of the status of the message. MsgShowMessage disposes of 
the string it receives a5 input. 


if the return value of the function is true, the application must update the 
rectangle in the window indicated by asg*.rect. 


If the application changes the value of the bex field of the FieldDescriptor 
(presumably te change the default position of the message), then all future 
stacking of messages will be in reference to this new position. 
MsgShowMessage only clears messages and prompts correctly if the default 
(base) position of the box is the bottom of the window. If the application 
alters the position of the box, it is responsible for clearing the messages 
and prompts with their respective clear functions. 


Parameters 


msg A pointer to the MessageStatus record for this message. 
str A pointer to the message text that is to be displayed. 


Function Return 


& boolean that, if true, indicates that the application must update the 
rectangle in the window indicated by asg*.rect. 


Asq@ShowPrompt 
FUNCTION MsgShowPrompt (msg : MessagePtr; str : StringPtr) : Boolean 
Purpose and Gperation 


This function erases the previous message(s) or prompt(s) before displaying 
the given string as a ane line prompt at the bottom of the window. The esa 
variable keeps track of the status o¢ the prompt. MsgShowPrompt disposes of 
the string it receives as input, 


If the return value of the function is true, the application must update the 
rectangle in the window indicated by esg*.-rect. 


If the application changes the value of the hex field of the FieidDescriptor 
(presumably to change the default position of the prompt), then all future 
stacking of messages will be in reference to this new position. MsgShowPrompt 
only clears messages and prompts correctly if the default (base) position of 
the box is the bottom of the window. If the application alters the position 
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of the box, it is responsible for clearing the messages and prompts with 
respective clear functions. 


Paraneters 


msq A pointer to the MessageStatus record for this prompt. 
str A pointer tothe prompt text that is to be displayed. 


Function Return 


@ boolean that, if true, indicates that the application must update the 
rectangle in the window indicated by esg*.rect. 
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MsgStackHMessage 
FUNCTION MsgStackNessage(msg + WessagePtr; str + StringPtr) : Boolean 
Purpose and Operation 
This function stacks a message on top of currently displayed messages. The 
asg variable keeps track of the status of the message. MsgStackMessage 


disposes of the string it receives as input. 


If the return value of the function is true, the application must update the 
rectangle in the window indicated by psg*.rect, 


Stacking a message on a prompt will first erase the prompt (stack of prompts} 
and then display the message at the bottom of the window. 


Parameters 


msg A pointer to the MessageStatus record for this message. 
str A pointer to the message text that is to be displayed. 


Function Return 


A boolean that, if true, indicates that the application must update the 
rectangle in the window indicated by esg*.rect. 
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MagStackPronapt 
FUNCTION MsgStackPromptimsg : MessagePtr; str : StringPtr) 1 Boolean 
Purpose and Operation 
This function stacks a prompt on top of currently displayed messages or 
prompts. The esg variable keeps track of the status of the prompt. 


NsgStackPrompt disposes of the string it receives as input. 


If the return value of the function is true, the application must update the 
rectangle in the window indicated by asg*.rect. 


Stacking a prompt on a message will place the prompt on top of the message. 
The resulting prompt-message block is considered a prompt for future message 
rules (See Chapter 6). 

Parameters 


msg A pointer to the MessageStatus record for this prompt. 
str # pointer to the prompt text that is to be displayed. 


Function Return 


A boolean that, if true, indicates that the application must update the 
rectangle in the window indicated by asg*.rect. 
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NewString 
es) FUNCTION NewString{maxLength: Word): StringPtr; 


Purpose and Operation 


NewString allocates memory for a new string of the given length and returns a 
string pointer to that area in memory. The maxLength that is passed as a 
parameter becomes the maximum length (max) of the new string, and the current 
length (len) is initialized to zero. If you try to refer to an element in the 
string beyond string*.chars(max] another variable’s memory area may be 
damaged. 


CAUTION: ONLY NewString and NewStringLit WILL PROPERLY ALLOCATE SPACE FOR 
THESE STRINGS. NEVER call NewiStringPtr) because New will allocate all 65535 
bytes according to the declaration of String.charsl!..65535] above. 

When declaring your own static variables to deal with strings, you must 
declare them to be StringPtrs, NOT Strings. If you declare a static variable 
as type String, the compiler will try to allocate 65535 bytes for 
String.chars({!..65535] according to the declaration of the String record. You 


should declare the variable to be of type StringPtr and then assign it with 
the value resulting from a cal] to NewString or NewStringLit. 


NewStringtlit 
® FUNCTION NewStringLit(VAR lit: Bytes): StringPtr; 
Purpose and Operation 
NewStringLit takes a literal string, allocates memory for it, and returns a 
string pointer. The maximum length (max) and current length (len) of the new 


string is the length of the literal characters. 


NOTE: The last character of lit must be a DEL character (CODE-SHIFT-hyphen). 
NewStringLit needs the DEL character to determine the length of the string. 


Example 
string := NewStringLit('The results areg’); 


The Ten and max of string are both 15. String*.chars is equal to ‘The results 
are’. 
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RealToString 


FUNCTION RealToString(aReal: LongReal; @ 
fracDigits: Integer}: StringPtr; 


Purpose and Dperation 


RealToString converts a fifteen digit real number into a string variable. 

(The 8087 numeric processor uses fifteen and a half digits of precision; this 
routine returns fifteen digits, rounding off the half digit as necessary.) 
Note that this routine produces real numbers of fifteen and a half digits. It 
cannot accomodate exponential notation, such as 6.03E+23. For details, see 
the Intel 8087 Floating Point Processor Manual or the Pascal Manual. 


The variable fracDigits determines how many digits after the decimal point 
will be included in the string. Any extra digits beyond fracDigits will be 
rounded. The maximum value for fracDigits is 16 places. Setting fracDigits 
greater than 16 is not recommended. Setting fracDigits to -1 will cause the 
routine to strip trailing zeros and to return only the significant digits of 
the number. If fracDigits is zero, then the rea} number is rounded to an 
integer (without a decimal point) and converted to a string. 


NOTE: If fracDigits = £5 and the integer portion of the number is greater than 
zero, then some of the numerals to the right of the decimal will be incorrect. 
For example: 


Q. £23456789012345 
£234. 123456789012222 @ 


The first number i5 accurate, but the final four digits of the second number 
("2222") are spurious. 


Although this function takes a LongReal parameter, it can also convert numbers 
of type Real and Longint. Real numbers can be used as parameters directly, 
because Pascal converts them to LongReals automatically, 


RealToString is the only function that can be used to convert LongInt numbers 
to strings. (The Longint type is not compatible with the Integer ToString 
function.) To convert a LongInt number to a string: 


VAR a: LongInt; 
b: LongReal; 
bss ay 
resultstring = RealToString(b,0); 
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SetBytes 


PROCEDURE SetBytes (value: Char; 
VAR dest: Bytes; count: Word); 


Purpose and Operation 


This procedure sets every byte in the destination area to the same given 
value. 


Parameters 
value The value that SetBytes will assign to every byte in the memory area. 
dest A pointer to the destination area in memory. 


count The length of the destination area, in bytes. 


SetPrefix 


PROCEDURE SetPrefix (subjectName: StringPtr); 


Purpose and Operation 


This is used by the application to set the prefix subject, ie. 
if the current prefix is ‘Hard disk'programs, then 
SetPrefix(NewStringLit(‘Incs ‘)) sets the prefix to 

“Hard disk’Incs. 
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SkipProperties 


PROCEDURE (conn: Word; @ 
VAR error: Word); 


Purpose and Operation 
Given a connection number of a file, this procedure automatically skips over 
all common properties records in a data file and moves the current file 


position pointer. Thus, a subsequent OsRead or GetNextRecord call would begin 
with the first record following the common properties. 


StringOfFormitem 


FUNCTIGN StringOfFormitem (VAR dataForm +: DataFormType; 
row : INTEGER) : StringPtr; 


Purpose and Operation 
This function returns a stringPtr to the text actually displayed in a form 


item. It can be used if you need to know the text of a choice selection as 
Opposed to the number of the choice. 


Paraaeters @ 


dataForm The form containing the desired text. 

row The row within the form containing the text of the desired choice 
selection. 

Function Return 


A stringPtr to the text of specified the choice selection. 
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® FUNCTION StringTolnteger (str: StringPtr; 
VAR converted: Boolean): Integer; 


Purpose and Operation 


This function converts a string value into an integer. The string must 
represent an integer between -32768 and 32767 inclusive for the conversion to 
succeed. The variable “converted” indicates whether the conversion was 
successful or not. 


StringToReal 


FUNCTION StringToReal(str: StringPtr; 
VAR converted: Boolean): LongReal; 


Purpose and Operation 


This function converts a string value into a real number. The variable 
“converted” indicates whether the conversion was successful or not. It will 
convert up to the first fifteen digits, and drop any extra digits without 
causing an error. If the conversion fails (from incorrect input, for example) 
the routine returns 0. 


Note that this routine produces real numbers of fifteen and a half digits. It 
cannot accomodate exponential notation, such as &.03E+23. For details, see 
the Intel B0B7 Floating Point Processor Manual or the Pascal Manual. 
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SubProperty 


FUNCTION SubProperty(Str : StringPtry 
index : Integer) : StringPtr; 


Purpose and Operation 


Picks a name out of a string made up of names and special characters. The 
special characters are delimiters in the GRiD-OS file system. 


Parameters 
Str The string that usually-represents s pathname. 
Index An index into the string that represents the 


significance of the desired token. 
Returns 
@ substring of Str that was contained between delimiters. The legal 
delimiters are: ~,',+, and Q. 
Example 
Tf Str = ‘WO'Programs’sample*text™ then 
SubProperty(str, 1) returns “WO 
SubProperty(str, 4) returns ‘text’. 
If Str = sample™textiGRiDiRG then 
SubProperty(str, 0) returns ‘sample’ 


SubProperty(str, 2) returns ‘GRiDiRG’ 
SubProperty(str, 3) returns NIL. 
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SubStringLit 


@ FUNCTION SubStringlLit(VAR lit: Bytes; 
delim: Char; 
count: Word): StringPtr; 


Purpose and Operation 


This function returns the Nth item (specified by count) from a literal 
containing text separated by delim characters. 


It's useful for constructing the ItemStr or ChoiceStr functional parameters as 
defined for menus and forms. For creating menus and forms, no carriage 
returns or line feeds should be embedded in the literal. 


Paraneters 

lit A pointer to a literal. All items should be concatenated 
together into a single literal, with the items separated from 
one another by delim characters. A delim character must follow 
the last item. 

delin The character that separates the items in the literal, It can 
be the literal character surrounded by single quotes, such as 

“or ‘/‘, or it can be the ASCII value, as in CHR(127). 

Most programmers use the DEL character as a delimiter -- ‘§' or 
CHR(127). While DEL characters appear as a solid square in the 
text editor, they do not appear on printouts. 

count An integer index to the substring of lit. 

Returns 


SubStringlit returns a StringPtr pointing to a copy of the substring. The 
substring does not include any DEL characters. 


Example 
If menuString = ‘COPYQMOVEBDELETES’ 


DEL characters 
then SubStringLit (menuString,‘@',1) returns a StringPtr containing ‘COPY’. 
Other legal calls include: 
CONST x = ‘a/b/c/' 


VAR A £1..40] of Chars 
substr: StringPtr; 
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substr SubStringLit(‘ReadOWriteQAppendO’, ‘@', 2); 
substr SubStringLit(x, '/’, 2) 
substr SubStringLit(string*.chars(1], ‘/', 2); 


substr += SubStringLit(A, CHR(157), 2)3 
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ThIiAddCol 


PROCEDURE ToiAddCol (chPerLine,iinesPerField: Integer; 
VAR table: Celljable; 
shouldAlioc : Boolean; 
editable: Boolean); 


Purpose and Operation 


This procedure appends another column to the CellTable matrix. The appended 
columns may have a different field width (characters per line) from the 
columns of the table being appended, By appending columns of different 
widths, you are not limited to tables of one width, such as the ones produced 
by ThilnitTabie, The number of lines in each field should be the same, 
however, 


You can specify whether the procedure should allocate memory space for the 
values of the appended fields or not. The appended fields can be editable or 
fon-editable, as well: TbhlAddCoi enables you to construct tables made up of 
both editable and non-editable fields. For example, questionnaire templates 
would include non-editable areas for the questions and editable areas for the 
responses, When you add a column, the constraint is widened to include it. 
It's best to modify the cursor‘’s constraint area after adding columns. 
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ThicelloOnScreen 


FUNCTION Tb1CellOnScreen({VAR table: CellTable; 
cell: Cellidd: 
Boolean} 


Purpose and Operation 


This function returns whether the cell is within CellTable.visible, i.e., 
whether it is to be displayed. This routine has NO relation to 
CellTable,visibleRect, the table's clipping rectangle. 


ThiChangeFields 


FUNCTION TbhiChangeFields(VAR table: CellTable; 
ch: Char): Boolean; 


Purpose and Operation 


This procedure, given a table and a movement character, moves the field 
outline from cell to cell. (It moves the cursor, too, if the cursor actually 
was in the currentCell,) Call it when EditTable returns a result of 
outOfField, and include the same ch character that you called ThlEditTable 
with, TblChangeFields will return False if it is unable to move in the 
indicated direction, meaning that scrolling is necessary. 
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ThiConfirmSelection 


PROCEDURE TblConfirmSelection(VAR table: CeliTabie); 


Purpose and Operation 


Call TbiConfirmSelection to save the source selection range for commands that 
require two selection ranges, such as Move and Duplicate. The table code will 
leave the source selection highlighted while the user selects a destination 


range. 


It performs these functions: 


It copies the Celllds and cursor positions in table.textcursor, 
table.anchor, and table.currentCell into table.sourceAnchor and 
table.sourceCurrent. The sourceAnchor and sourceCurrent Cellids are 
“normalized” so that sourceAnchor is the top left cell of the 
selection range, and sourceCurrent is the bottom right cell of the 
range. Both celis are corrected for scrolling ~- table.scroliCell is 
added to them. (This has the same result regardless of whether 
scrolling is easy or difficult case.) 


It sets (table.anchor.pos} to nowhere, which will keep that value 
until the user presses CODE-B to select a destination range later. 


The variable table,whichParameter is set to 2, indicating that the 
user must select another parameter (such as a character position or 
Cellid) to complete the command. 


ThIiDimHilightCell 


PROCEDURE ThIDimHilightCell (VAR tables CellTable; 


cell: Cellid); 


Purpose and Operation 


This procedure draws a dashed outline around a cell. 
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ThiDdisposeScreen 


PROCEDURE TbiDisposeScreen(screen: ScreenPtr; 
colCount: Integer); 


Purpose and Operation 


TblDisposeScreen deallocates screen arrays that have been created by 
TblNewScreen. The variable colCount represents the number of columns to be 
disposed of; it must equal the number of columns that were allocated when the 
screen arr€ ThlDisposeCol (col: ColPtr; rowCount: Integer); 


Furpose and Operation 

The procedure deallocates column arrays that have been created by TbINewCol. 

The number of rows (rowCount) to be disposed of must equal the number that 

were allocated when the column array was created. 
ThiDisposeTable 


PROCEDURE TbiDisposeTable(VAR Table: CeliTable; 
shouldDispose: Boolean); 


Purpose and Operation 
This procedure disposes of the specified cell table. It can dispose of the 


values of the fields in the table or retain them, according to these values of 
shouldDispose: 


shouldDispose = operation 

disposetext dispose of the values of 
(True) the fields 

dontDisposeText keep the values of the 
(False) fields 


When shouldDispose = dontDisposeText, the procedure disposes of the table 
pointers and the field descriptors, but retains the values of each field. You 
aight want to retain these values when other pointers need the values. 
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ThiDdrawGrid 


& PROCEDURE Tb1DrawGrid (VAR table: CellTable); 


Purpose and Operation 


Draws a frame around the visiblekect and grid lines between the fields of a 
table, if table.frame, table.verticalGrid, and table. horizontalGrid are True. 
If a variable is False, TblDrawGrid does not draw the graphics associated with 
it. It does not redraw the fields of the table. The frame and grid lines are 
one pixel wide. 


TbhIiDrawTabie 
PROCEDURE ThIDrawTable(VAR table: CellTable); 
Purpose and Operation 


The procedure clears all] fields from the screen and redisplays them with their 
curreat values, by calling FldDrawField for every field in the table. It 
overwrites the entire area defined by the visibleRect. 


lf table.verticalGrid and CellTable.horizontalGrid have been set to True, then 
the routine will draw lines between the fields. If table.frame is True, then 
it will draw a one-pixel frame outside table.visibleRect. (The frame is not 
within the coordinates of table.visibleRect). 


Application Note: To draw a newly initialized table, your application must 
call TbhlDrawTable (to draw the fields) and TblHiliphtTable (to draw the cursor 
and to outline the cursor’s cell). Later, TblEditTable and TblChangeFields 
will update and redisplay the table when the application modifies it; they 
redraw the table, the cursor, the cell outline, and the range selection (if 
any}. 
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ThLiLEditTable 


FUNCTION ThlEditTable(VAR table: CellTable; 
ch: Word): FieldEditResult; 


Purpose and Gperation 


This all-purpose table routine inserts characters at the current field 
location and cursor position, performs various key functions, and redraws both 
the display and the cursor. Cali it once for every character read from the 
keyboard. It does not redraw the entire table, but just the changed field. 


The routine recognizes BACKSPACE, CODE-BACKSPACE (erase previous word), 
RETURN, and arrow keys. 


Tf the value of the ch character belongs to the set of CellTable.commandKeys, 
the currentCel] will be displayed in inverse video, and the selection 
mechanism will be turned on. That is, when the user types a selection 
command, the current cell is inverted to show that a selection has begun. 


Returns 


After attempting to insert a character or perform a function, Thl&ditTable 
returns one of these values: 


ok The procedure successfully processed a character, such as an 
arrow key, but did not change the contents of the cell. 


processed The procedure processed a character that changed the cell's @ 
contents. This includes inserting, modifying, or deleting text 
characters in the cell, <¢DDES THIS HAPPEN YET? ALSO ESCAPED? 
7/30 UPDATE SAYS NO>> 


escaped The user pressed ESC, and nothing was done to the contents of 
the cell. Any selections are cleared, and the table leaves 
command mode. 


ignored The procedure received a character that it did not know how to 
process. By testing for this result, you can allow terminal 
eaulation characters (such as CTRL characters) to pass through 
the application to another application or processor. 


outOfField An attempt was made to move the cursor out of the cell. 
TbhlEditTable doesn’t actually move the cursor out of the cell. 
Call TblChangeFields to do so. 


bufferFull The text string of the cell is full. It cannot contain any 
additional characters. 


Note: if the text pointer of a fieid descriptor is nil, then 


ThlEditTable returns bufferFull as well. That is, if no text 
string has been allocated for a celi, then that cell’s text 


8 
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fieldFul] 


buffer cannot accept text and will therefore appear to be full. 


The text buffer is not full, but not all the characters in the 
cell can be displayed. The character is inserted into the cell 
anyway. A fieldFull result occurs when the user presses 
SHIFT-RETURN or types enough text to fill the displayed area of 
the cell. 8y checking for the fieldFull condition, the 
application can then add another line of vertical space to the 
cell. (To keep scrolling and selection consistent, you must add 
another line to every cell in the row using Tb1ChangeRowHeight.) 
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TolEquaiCeils 
FUNCTION Tbhi€qualCelis(celli,cell2: Cellid):Boolean; 


Purpose and Operation 


1f the given CellId’s are equal, ThlEqualCells returns True. 


ThliEscapetiade 
PROCEDURE TbhiEscapeMode (VAR tables CellTableds 


Purpose and Operation 


This procedure puts the table into the norma! (non~command) state, wn-inverts 
any cell or text selection ranges, but leaves the cursor and the highlighted 
cell on, 
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ThiFieldorCeliiad 


ie) FUNCTION ThiFieldQfCellId(VAR table: CellTable; 
: cell: Cellid)s FieldPtr; 


Purpose and Operation 

This function converts a Cellid into a FieldPtr reference, which makes table 

values easier to refer ta and to change. It is useful when working with cell 

variables of type Cellid, such as currentCell. 
ThiFieldorColRow 


FUNCTION ThlFieldOfColRow(VAR table: CellTable; 
col, row: Integer): FieldPtr; 


Purpose and Operation 


This procedure, given a column and and a row of a cell table, it returns the 
pointer to the field. These two references return the same pointer value: 


ThiFieldOfColRow(tablel, 4, 2) 
tablel.screen*££1*C2) 


ThiFindBounds 


PROCEDURE TblFindBounds(VAR table: CellTable; 
VAR rect: Rectangle; 
VAR left, right, 
top, bottom: Integer); 


Purpose and Operation 
This procedure calculates which cells lie within a rectangle that has been 


defined in the pixel coordinates of the display window. Given an area on the 
screen, it allows you to update only a portion of the table. 
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ThiGetSelectedCellids 


PROCEDURE ThlGetSelectedCellIds(VAR table:CeliTable; 
VAR first, last: Cellid)s 


Purpose and Operation 


This subroutine is used for the "difficult case” of scrolling. It locates the 
movingCell and anchor Celllds, rearranges them in ascending order, adjusts 
them from relative “unscrolled” CellIds to absolute “scrolled” Cellids, and 
returns them as “first” and "last" absolute (logical) coordinates. 


When referring to a selection, call TblGetSelectedCellids instead of 
referencing the anchor and movingCel] directly. The movingCell could be 
located either before or after the anchor, but the variables "first" and 
"last" prevent any errors that could arise from this ambiquity. 
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TbhiHtLightCell 


@ PROCEDURE TbiHilightCell (VAR table: CellTable; 
= cell: Celild); 


Purpose and Qperation 


This procedure, given a CellTable and a Cellld, it draws the appropriate 
outline around a cell, based on the value of hilightKind. 


ThikHilightTable 
PROCEDURE ThIHilightTable(VAR table: CellTable); 
Purpose and Operation 


This procedure draws the cursor in the currentCell, inverts any selected range 
of cells, and highlights all cells in the table that require highlighting. 


NOTE: The variable table.hilightOn stores whether the highlighting is on or 
off. You can call TblHilightTable repeatedly, and the table will remain 
hilighted each time (rather that inverting from highlighted to unhighlighted). 
Do NOT erase the window while the table thinks its highlight is on, however. 
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ThiInitTable 


PROCEDURE TblInitTable(colPerScreen,rowPerScreen, 8 
chPerLine,linesPerField: Integer; 
topLeftMargin, 
fieldGap: Point; 
VAR table: CellTable; 
shouldAlloc: Boolean; 
editable: Boolean; 
commands: keys); 


Purpose and Operation 


ThlInitTable initializes and formats the CellTable it receives as an argument. 
Every cell within the initialized CellTable will be identical, with a uniform 
number of characters and lines in a field, 


The procedure sets the current cell to column 1, row 1 of the CellTable, and 
initializes the cursor tp that field, as well. It initializes the constraint 
and visible areas to the bounds of the entire table, It sets 

table. headingRows and table.headinglols both to zero. 


Paraneters 

colPerScreen The number of vertical columns per table. 

rowPer Screen The number of rows per table. 

chPerLine The maximum number of characters allowed in each line of a @ 
field, 

linesPerField The maximum number of lines allowed in each field -- 


especially useful for producing multi-line fields. 


topLeftMargin The top left margin of the top left cell. Its x component is 
the horizontal distance in pixels from the left window bound 
to the top left pixel position of the top left field, Its y 
component is the vertical distance from the top window bound 
down to the top left pixel position of the top left field. 


fieldGap The distance in pixels between fields, as they are displayed 
on the screen. The x component is the horizontal distance 
between field boundaries; the y component is the vertical 


distance. 
table The CellTable to be initialized by this procedure. 
shouldAlloc A parameter to the procedure which specifies whether memory 


space should be allocated for the field values. If 
shouldAlloc = allocText, the procedure will allacate the 
space; if shouldAlloc = dontAllocText, it sets the text 
pointer to nil and doesn’t allocate any space. If you 


C 
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editable 


commands 


allocate the text after you've initialized the table, be sure 
to allocate strings with a maximum width no longer than the 
width of the columns in the table (chPerLine is the column 
width). 


A Boolean variable that determines whether or not all fields 
in the table can be edited by the user. The fields are 
allocated as editable or non-editable regardless of the value 
of shouldAlloc. You can modify the editable property of any 
individual field by changing 
table.screen*{column3*Crow]*. kind. editable, 


The set of legal command Keys for this particular table. 
Names for the Keys in the set can be found in the Keys.inc. 
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TbhoilInvertRange 


PROCEDURE TblinvertRange({VAR table: CellTable); ( + 


Purpose and Operation 


This procedure inverts the current selection range, either a range of cells or 
a range of text within a single field. A range is a rectangular span of cells 
that has been selected by the user, Nothing will happen if the procedure is 
called and no range has been selected. (To see whether a range has been 
selected, examine the variable table.anchor: if table.anchor.pos = nowhere, 
then no range has been selected.) 


TéoLlIinvertSpan 


PROCEDURE ThlinvertSpan(VAR table: CellTable; 
col!, ¢ol2, rowl, row2: Integer); 


Purpose and Operation 


This procedure, given a span of cells, inverts the displayed cell of each 
field within the span. Spans are rectangular areas defined by column and row 
Parameters, TblinvertSpan will invert the additional selections when a user 
scrolls during a selection, 


@ 


TbhiNewScreen 
FUNCTION ThiNewScreen(colCount: Integer}: ScreenPtr; 
Purpose and Operation 


This function returns a pointer value to a screen array with the given number 
of coluans, colCount. 
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Tbhiscreilil 
PROCEDURE TblScroll (VAR table: CeliTable; ch: Char); 
Purpose and Operation 
This procedure is used for the “easy case" and scrolls the view of the table 
in the direction indicated by ch (left arrow, right arrow, up arrow, or down 


arrow), and updates the display. It also updates visible and constraint so 


that they match the displayed area. TblScroll uses bitblt software for rapid 
scrolling. 
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ThiScrellAdjustCelild 
PROCEDURE TbiSecrollAdjustCelli¢ @ 
(VAR table: CellTable; 
VAR unscrolled, 
scrolled: Cellid); 
Purpose and Operation 


This routine transforms an "unscrolled” Celild that is relative to the display 
screen into an absolute “scrolled” Cellid, according to these formulas: 


scrojlled.col = unscrolled.col + (scrollCell.col - 1) 
scrolled.row = unscrolled.row + (scrollCell.row - 1} 


It returns the adjusted result in the variable "scrolled.” 
Example 
When scroliCell = [3,4], the absolute Cellid of the top left cel] in the table 
display (screen*C13°C13) is col = 3 and row = 4. ThlSeroliCell would map 
unscrolled = (1,1) into scrolled = (3,41. 

ThisetCurrentCell 


PROCEDURE ThlSetCurrentCell (VAR table:Cell Table; 


col, row: [nteger); @ 


This procedure sets CellTable.currentCel] to the given column and row of the 
cellTable. This routine will change the position of the cursor and the 
highlighted cell. The display will change only when another procedure redraws 
the table, however. 


Purpose and Operation 
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ThiSetVisible 
O PROCEDURE ThlSetVisible(VAR table: CeliTable); 
Purpose and Operation 


This procedure adjusts table.visible and table.constraint so that they lie 
within the table.visibleRect clipping rectangle. Before you call 
ThiSetVisible, set table.visible.top and table.visible.left to the top left 
Cellid that you want to be visible on the screen. (They are both initialized 
to 1 by ThlInitTable,) TbiSetVisible calculates the other values based upon 
these two, 


When ThlSetVisible executes, it will adjust table.visible.right and 
table.visible.bottom so that visibleRect is filled with cells or portions of 
cells. Portions of cells can be visible, too; the cells are clipped at the 
boundary of the visibleRect clipping rectangle. 


The procedure adjusts the top, bottom, left, and right of table.constraint as 
well. Constraint is based upon the number of entire cells that can fit within 
visibleRect. TblSetVisible does not allow constraint to contain cells that 
appear only partially on the screen. This restriction ensures that the cursor 
and cell] outline can move into entire cells only. 


Note that if table.visible overlaps table. headingCols or table.headingRows, 

the constraint area will be even smaller. Heading Columns or Rows can be 

visible, but the cursor and cell outline cannot move into them ~- so the 
& constraint area must be correspondingly smaller. 


ThiSsStartSelectioaon 
PROCEDURE TblStartSelection(VAR table: CeliTable; ch: Char); 
Purpose and Operation 
This procedure puts the table into command mode and sets table.commandChar to 
ch. It works the same as if the ch character had been included in the set of 
keys (in table.commands) passed to TblInitTable, and then TblEditTable was 


called later with that character. In both cases, highlighting of selections 
is enabled, 
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ThitnhilightTable 
PROCEDURE TblUnhilightTable(VAR table: CellTable); @ 
Purpose and Operation 
This procedure, given a cell table, erases the cursor, uninverts any range of 
selected cells, and removes the highlighting from any highlighted cells. The 
cursor is erased graphically only, 50 you must reset it elsewhere with 


TolSetCursor. 


Tb1UnhilightTable also depends upon table.hilightOn for its status -- see the 
note under ThiHilightTable. 


TohltpdateRect 


PROCEDURE ThlUpdateRect (VAR table: CellTable; 
VAR rect: Rectangle); 


Purpose and Operation 
This procedure updates the cells that lie within a rectangle defining a 
portion of the display window. Given an area on the screen, it allows you to 


update only a portion of the table. It is useful for redrawing the table 
after a message, a menu, or a form has been displayed. 
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TimeToString 


FUNCTION TimeToString(format : Byte; 
epoch + TimeType) + StringPtr; 


Purpose end Operation 


Converts time and date information from the O§ to a string for easy use in an 
application. 


Parameters 


format Currently ignored; it will be used to arrange the 
string information differently. 


epoch Data that the OS returns from the system clock. 


TYPE TimeType = RECORD 
year ; WORD; 
month, day : BYTE; 
hour, minute, second : BYTE; 
tenthO¢Sec, dayOfWeek : BYTE; 
dayOfYear : WORD; 
END; 


Returns 


The string is of the form: ‘20-Jan-83 11:00 am’, Other forms may be 
available at a later date. 
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TranslateHeading 


FUNCTION TranslateHeadinglinputStr : StringPtr; 
width : Integer; 
pageNum : Integer) : StringPtr; 


Purpose and Operation 

This routine translates the input into a centered output string for printing 
an an Epson printer. Special symbols are translated in the upper or lower 
Case. The output string will be no wider than the width parameter, regardless 
of the number of symbcls included or the length of the input string. 

Special symbols: “P (page number) 


“D (date) 


ie, a call to TranslateHeading with parameters: 


inputStr = ‘Some file name “D She Ake 
width = 40 
pageNum = 5 


will return a string looking like: 


‘Some file name 5/09/B3 8:33 am 5° 
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UnDeDataForn 


PROCEDURE UnDoDataForm (VAR dataForm : DataFormType; 
3) eraseDataForm : ROOLEAN); 


Purpose and Operation 


This procedure deallocates all the tables and internal structures associated 
with a data driven form. It does not, however, free the strings in the form 
(You must use FreeStrings!nDataForm), UnDoDataForm should always be called 
after DataFormConfirned, 


Parameters - 


dataForm The form whose tables and internal structures are to be 
deallocated. 

eraseDataForm This Boolean determines whether the form will be erased after 
it has been confirmed. If set True, the form is erased: this 
is the technique used by most GRID applications. If special 
circumstances dictate, you can leave a form displayed after it 
has been confirmed by setting this parameter False. 
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UpperCase 
FUNCTION UpperGase(ch: Char}: Char; 8 
Purpose and Operation 


This function converts any lowercase alphabetic characters in the string to 
uppercase. It does not shift up numerals, punctuation, or special characters. 
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APPENDIX Ar INCLUDE FILES 


Include files are tools for the development environment. The content of each 
include file is a PUBLIC section of Pascal (or PLM) code that describes the 
interface to a corresponding Pascal (or PLM) module. 


The structure of the files varies from that of the Pascal module for the sake 
of symbol table space in the compiler. Constants and types are usually 
included in one file, with functions and procedures in another. This allows 
easy reference for types that are defined in terms of other constants 
(parameters). 


This structure makes the number of files necessary for successful compilation 
larger, but it saves on symbol space if the total number of included symbols 
is smaller in the end. This restriction on symbol space in the compiler has 
been improved with the latest release of the Intel compiler. The present file 
convention, however, will stand, 


Lastly, the interface is purely for the use of the Pascal compiler, It should 
net be used as an External Reference Specification, or associated 
documentation. Writing programs that interface with external modules requires. 
knowledge of the operations and their effects on the private data structures 
of a module, Much like a programming language is an implementation of a 
grammar, so include files are only a definition of an interface. 


BEFORE COMPILING 

To use Common Code routines, your source code must refer to the Common Code 
Include Files listed in Table A-1, This table lists all the include files for 
the Common Code -- the files that contain declarations of data types, 


functions, and procedures. 


You include files with the #INCLUDE statement, as described in the PASCAL-B4 
User’s Guide. The files must be available on-line during a compilation. 


Include Files A-1 


Yeu do not have to include all of the files listed in Table A-1!. Your source 
program generally needs to include only the procedures that it calls. For 
example, an application that uses only the window graphics routines and the 
string routines would anciude only WindowFrocs.inc™Text™ and 
StringProcs.inc*Text*. (It would also need to include the data types defined 
ain StringTypes.inc*Text* and WindowTypes.ine*Text™.)} 


However, some packages refer to the data types defined in other packages. For 
instance, the Menu/Form routines need the data types defined in several] other 
fackages. Figure A-1 illustrates these dependencies. A package at one level 
requires all the data types defined on the level below it. For example, a 
program containing messages or prompts would require these include files: 


MessageProcs.inc*Text” 
MessageTypes.inc*Text” 
FieldTypes.inc*Text” 
StringTypes.inc™Text™ 
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Common Properties 


Commands 


Message/Prompt 


Byte Manipulation 
Fonts 


Table I-1. 


Include File Names 


Common. ine™Text” 
Keys.inc*Text” 

Math. inc*Text* 
StringTypes.inc*Text”™ 
StringProcs.inc*Text™ 
RealStringProcs.inc*Text” 


FieldTypes.inc*Text™ 
FieldProcs.ine*Text™ 


TableInitTypes.inc*Text™ 
TableInitProcs.inc*Text™ 


TableEditTypes.inc*Text™ 
TableEditProcs.inc*Text” 
DataForms. Inc*Text™ 


FileFormProcs.Inc*Text™ 
FileFormTypes.Inc*Text™ 


MenuFormTypes.inc™Text” 
NenuFormProcs.inc™Text™ 


CommonPropsProcs. Inc*Text 
CommonPropsTypes. Inc*Text 


CommandProcs. Inc*Text™ 


MessageTypes.inc*Text™ 
MessageProcs.inc*Text” 


ByteProcs.inc*Text” 
FontProcs. Inc*Text” 
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APPENDIX B. LISTINGS OF DATA DRIVEN MENU/FORM EXAMPLES 


This appendix lists the PLM and Pascal source modules and Jink command 
statements (as they might be entered with the GRiDDevelop “Link" token) used 
for the examples of data driven menus and foras described in Chapter 8. The 
files and link command for the menu example appear first, followed by those 
for the form example. 
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PLM MODULE FOR EXAMPLE "MENU" 


$COMPACT NOLIST 
MenuPLi: DO; 
$INCLUDE (*w'Incs'PlmLits. Inc*Text” 
JRERERERAREEEEEH Sample MONd HREREEEEEEE EERE / 
DCL sampleMenuTemplate (#) BYTE PUBLIC DATA 
(‘Save this file”’, 
"Exchange for another file*’, 
‘Include a file”, 
‘Write.to a file”’, 
‘Append a file’, 
"Erase a file”'’, 
‘Show characteristics of a file™i’); 
DCL theBampleNenu PTR PUBLIC DATA (@sampleMenuTemplate); 


END} 
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@ 


SOURCE FILE FOR EXAMPLE PROGRAM "MENU" 


$NOLIST COMPACT 

MODULE Main; 

SINCLUDE (‘wO" Incs Common. Inc*text™) 
SINCLUDE (‘wO'Incs'ConPas. Inc*text™) 
SINCLUDE (‘wO'Incs’ DataForms, Inc™text™) 


SINCLUDE (‘wO'Incs'FieldTypes.Inc*’text™) 
$INCLUDE (‘wO'Incs’FieldProcs. Inc*text™) 


SINCLUDE ('wO'Incs'MessageTypes. Inc’text™) 
SINCLUDE ('wO'Incs‘MessageProcs. Inc*text™) 


$INCLUDE (*wO'Incs’StringTypes. Inc*text™) 
$INCLUDE (‘wO'Incs StringProcs. Inc™text™) 


$INCLUDE (‘wO'Incs WindowTypes. Inc*text™) 
$INCLUDE (*wO‘Incs WindowProcs.Inc*text™) 


$INCLUDE (‘wO'Incs OsPasTypes. [nc™text™) 


PUBLIC MenuPLh; 
VAR theSampleMenu: DataMenuType; 


PROGRAM Main; 


CONST 
{ miscellaneous strings } 
sampleMsg = ‘Sample: ‘3 
selectiso = ‘ Select item and confirm ‘3 
VAR 
windowRect: Rectangle; 
cursor: CurserDescriptor; 
msgs MessagePtr; 
chs CHAR; 
55 


} 

PROCEDURE InitDisplay; 

VAR windowExtent: Point; 

BEGIN 
ConDefCsr (FALSE); 
WinInitDefaultWindows 
WinGetWindowExtent (windowExtent); 
FidStartKeys (cursor); 
asg = Msginit; 


WITH windowRect DO ¢ entire window for use with menus and forms } 
BEGIN 
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topleft.x += 0; 
topLeft.ey 2= OF 
extent i= windowExtent; 


PROCEDURE SampleNenu; 
VAR str: StringPtr; 
rect: Rectangle; 
itemSelected: INTEGER; 
confirmed: BOOLEAN; 
BEGIN 
str r= ConcatlLits (Samplemsg, Selectsg); 
rect += windowRect; 
confirmed := DataMenuConfirmed 
(theSampleMenu, 
msg, 
str, 
rect, 
cursor. keyProcess, 
itemSelected, 
ch); 


IF confirmed THEN 
BEGIN 
CASE itemSelected OF 
i: {do appropriate action for ‘save‘} 
2: {do appropriate action for ‘exchange’) 


? 
i 
3: 3 (do appropriate action for ‘include’? 
: 3} {do appropriate action for ‘write’? 
5: } (do appropriate action for ‘append’? 
6: 3 {0 approptiate action for ‘erase’? 
7: 3 (do approptiate action for ‘erase’} 
8: ; {do approptiate action for ‘erase‘} 
OTHERWISE; 
END; 
END; 
END; 
€ THIS IS THE BEGINNING DF THE PROGRAM 
? 
(seen en nnn nnn nn nnn nnn nnn ene nnn nn ne enn enn nnn een e neem ne nn ne 5) 
BEGIN 
InitDisplay; 
SanpleMenu; 
END 
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PLM MODULE FOR EXAMPLE "FORM" 


$COMPACT NOLIST 
Fora@PLM: DO; 
SINCLUDE ('w'Incs'PlmLits. Inc™Text™) 


/HERHHREAREEHEED Sample form HEREREEEEER ERED / 


DCL sampleForaitemCount LIT ‘7°; 
DCL sanmpleForaRowSize LIT ‘98’; /# 14 times item count #/ 


DCL sampleFormLabelsAndChoices (#) BYTE DATA 
(Editable numeric field*’An integer™:’, 
‘2Choice only field*First choice’Second choice™!‘, 
‘$Editable/choice field”A text string”A choice*!', 
‘,Editable real number field*A real number™:’, 
‘&Typeface™t', 
‘¢Printer™)', 
“sPlotter™)')5 


DCL theSampleForm STRUCTURE 
(form PTR, 
numitems INTEGER, 
labelsAndChoices PTR, 
choiceLines INTEGER, 
rows (sampleFormRowSize) BYTE) 


PUBLIC DATA 


(nullPtr, /* fora “/ 
sampleForaltemCount, /* nualtems a/ 
@saapleFormLabel sAndChoices, /* items */ 
My /*® choiceLines #/ 


END; 
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LINK COMMAND FOR EXAMPLE PROGRAM “MENU 


sLink Menus 

dink ‘wiobjs'Menu.PLM”Obj*, ‘w'objs'Menu.Pas”0bj”™, 
‘w'Libs'CompactSystemCalls*Lib* TO Nenu“Run” NOPRINT Purge BIND Fastload 
SE(STACK (+1000)) 
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® PASCAL LISTING FOR EXAMPLE PROGRAM "FORM 
$NOLIST COMPACT 
MODULE Main; 


SINCLUDE (‘wO*Incs*Common.Inc*text™) 
SINCLUDE (*wO*Incs*ConPas.Inc™text™) 


SINCLUDE (‘wO'Incs’FontProcs.Inc”text™) 
SINCLUDE (‘wO'Incs'DataForms. Inc*text™} 


SINCLUDE ('wO’incs’FieldTypes. Inc*text*} 
$INCLUDE (*wO'Incs'FieldProcs.inc*text™) 


SINCLUDE (*wO'Incs MessageTypes. Inc*text™) 
SINCLUDE (*wO'Incs'MessageProcs. Inc*text™) 


SINCLUDE (*wO'Incs’StringTypes.Inc*text™} 
SINCLUDE ("wO'Incs'StringProcs. Inc*text™) 


FINCLUDE (*wO'Incs' WindowTypes. Inc*text™) 
SINCLUDE ("wO'Incs’WindowProcs. Inc*text™) 


SINCLUDE (*wO*Incs'OsPasTypes.Inc*text™) 


al PUBLIC FormPLM; 
VAR theSampleForm: DataFormType; 


PROGRAM Main; 


CONST 
€ miscellaneous strings } 
sampleMsg = ‘Samples ‘j; 
filliInFormMsg = " Fill in form and confirm ‘; 
maxStringLength = 80; 
VAR 
windowRect: Rectangle; 
cursor: CursorBescriptor; 
msg: MessagePtr; 
ch: CHAR; 
code: WORD; 
theNumber: INTEGER; 
curChoice2: INTEGER; 
theString: StringPtr; 


curChoice3: INTEGER; 
theRealNuaber: REALS 

curChoice4: INTEGER; 
curFont: INTEGER; 
curPrinter: INTEGER; 
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curPlotter: 


INTEGERS 


PROCEDURE InitDisplay; 
VAR windowExtent: Point; 
BEGIN a 
ConDefCsr (FALSE); 
WinInitDefaultWindow; 
WinGetWindowExtent (windowExtent); 
FldStartKeys (cursor); 
sg t= MsgInit; 
WITH windowRect DO { entire window for use with menus and foros } 
BEGIN 
topLeft.x := 0; 
topLeft.y s= 0; 
extent 3= windowExtent; 
END; 
END; 


PROCEDURE InitVars; 


BEGIN 

theNuaber 1= 03 

curChoice2 me dy 

theString NewString (maxStringLength); & 
curChoice3 22°23 

theRealNuaber := 5.0; 

curChoice4 re Ly 

curFont ; 

curPrinter 23 

curPlotter ; 


WITH theSaapleForm DO 


BEGIN 


rowsliJ,theData.number := 


rows(1].currentChoice 
rows(2}.currentChoice 


rows{3i.theData.string := 


rows{3).currentChoice 


rows(4].theData.realNumber := theRealNumber; 


theNumber; 
1; 
curChoice2; 


ExactCopyOfString (theString); 


curChoice3; 


rows{4),currentChoice := curChoice4 
rows{5].currentChoice curFaont} 
rows{éJ,currentChoice += curPrinter; 
rows{7].currentChoice += curPlotter; 
END; 
END; 
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PROCEDURE SanpleForn; 
VAR itemSelected: INTEGER; 
confirmed: BOOLEAN; 


rects “Rectangle; 
stri StringPtr; 
BEGIN 


str := ConcatLits (SampleMsg, FillInFormMsg); 
rect :> windowRect; 


confirmed := DataForaConfirmed: 
(theSampleFora, 
normal DataFora, 
MSOs 
str, 
rect, 
cursor, keyProcess, 
ch)y 


IF confirmed THEN 
WITH theSampleForm DO 
BEGIN 
FontSetNth (theSampleForm.rows(5).currentchoice, cade); 
END; 


UndoDataForm (theSampleForm, TRUE); 


END; 


BEGIN 
InitDisplay; 
InitVars; 
SampleFornm; 

END 
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LINK COMMAND FOR EXAMPLE PROGRAM "FORM" 


tLink Forms: 

link ‘w'objs‘Form.PLM*Gbj”, ‘w'objs'Form,Pas*0bj”, 
“w'Libs’CompactSystemCalls*Lib* TO Form™Run™ NOPRINT Purge BIND Fastload 
SS(STACK (+1000)) 
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APPENDIX C. MENUS & FORMS: ANOTHER METHOD 


The data driven menus and forms techniques described in Chapter 8 greatly 
simplify implementation of these handy data gathering mechanisms. Previously, 
a much more complicated technique was used to implement the menus and forms. 
We will describe this earlier, more complicated technique for two reasons: 


9 


Some applications were developed before the availability of the data driven 
technique and associated calls. Users who are already using the earlier 
technique may find it impractical to convert existing programs to the new 
technique and may wish you use existing code to implement additional menus 
and forms. 


There are some things that you can do with the older technique that are not 
supported by the data driven technique. For example, you cannot create 
"dynamic" menus and for@s with the data driven technique. A dyna@ic menu 
or form is one where you can vary the appearance and contents of the form 
each time it is presented depending on what activities have taken place 
Since it was last displayed. An example of a dynamic form is the File 
form. Refer to the description of the File form and the FileFormConfirmed 
function in Chapter 8 for an iliustration of a dynamic fora. 


The calls described in this appendix create the data structures needed for 
menus and foras, and enable the user to add or modify their contents. 


DATA BTRUCTURES 


Figure E-1, "Nenu/Form Pointer Structure," illustrates how these data 
structures are related to one another and to the data structures in the 
chapter on cell tables. 
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MenuFormDesctiptor e 
MenuFormPtr rae Celltabie : 
: (See Figure 11-1 
Pointer 


Figure C-i. Menu/Form Pointer Structure 


* TYPE MenuForadeseriptor = 
RECORD 
table, choiceTable: Cell TablePointer; 
obscuredRect ,choiceRect: Rectangle; 
choiceLines: Integer; 
END; 


This record specifies the cell table as either a menu or a fore, and stores 
the appropriate parameters for them. Never alter any of the contents of the 
MenuForm Descriptor, except to read the Cell]Table pointer to reference the 
cell table settings directly. 

® TYPE CelifablePtr = “CellTable 


This pointer lets you keep track of different cell tables. 


* TYPE MenuForaPtr = “MenuForeDescriptory 


This pointer enables you to keep track of different menus or forms at once. 
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* TYPE ChoiceRequest # (choiceCountRequest, 

choiceCurrentRequest, 

choiceSetCurrent, 

choiceLeavingltem, 

choiceEnteringltem); 
The menu package uses a variable of this type to specify the choice fields of 
a form. A variable of this type can represent the different requests as 
follows: 


Kind of request Neaning 


choiceCountRequest Requests the total number 
of choices that the 
form should provide. 


choiceCurrentRequest Requests the string for the 
specified choice that is associated 
with a specified item. 


choiceSetCurrent Indicates the choice 
currently designated by the 
highlighted box. 


choiceLeavingltea Indicates that the user 
has moved the outline to 
a different item. 

choiceEnteringlten Indicates that the outline 
is about to move to a 
different item. 


# TYPE UpdateKind = (dontUpdate, updateTop, 
updateBottom, updateForward, 
updateBackward) ; 


This data type accompaniew the ScroliKey function used in MenuForeConfiraed. 
Do not use this data type or erase it from the include files. 
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MENU AND FORM ROUTINES 


initialize, menus and forms, one routine handles the menu or form when it is 
confiraed, and one routine disposes of a menu or form. While only four 
routines are provided, several of these routines are quite complex and 
incorporate a number of subfunctions. Each of the routines is described in 
complete detail later in this appendix. 


Four routines are provided to handle menus and forms. Two routines set up, or e 


MenulInit Creates and initializes a menu having a single column of 
choices. It requires the number of items in the menu, the 
string setting of each item on the menu, and the location 
on the window where the menu will be drawn. 


Foralnit Creates and initializes a form with a non-editable column 
of items and column of choices, which may or may not be 
editable. 


MenuForaConfiraed This all-purpose function returns True when the user 
confirms a menu selection or new values on a form It 
returns False if the user escapes out. 


MenuFormDispose Deallocates the menu or fora pointed to by the 
MenuFormPtr. It disposes of everything, including all the 
text. 


Duaay Functions 


These functions should be passed as dummy functional parameters to 
MenuForaConfirmed whenever it controls a menu, or a fora with no choice 
fields. They are never called. 


NilChoiceProc A dumay functional parameter, which should be passed in @ 
place of the ChoiceStr functional parameter to 
MenuForaConfirmed. 

NilChoicelnfo A duamy functional parameter, which should be passed in 
place of the ChoiceInfo functional parameter to 
MenuForaConfirmed. 

NilltemStr fA dummy functional parameter, which should be passed in 
place of the ItemStr functional parameter to 
MenuforaConfirmed, 

NilScrollKey A dumay functional parameter, which should be passed ia 
place of the ScrollKey functional parameter to 
MenuForaConfirmed. 
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MenuInit 


FUNCTION MenuInit (usableRect: Rectangle; 
itemCount: Integer; 
FUNCTION ItemStr(index: Integer 
dy: StringPtr 
d: MenuFormPtr; 


Purpose and Operation 


This procedure creates and initializes a menu having @ single column of 
choices. It requires the number of items in the menu, the string setting of 
each item on the menu, and the location on the window where the menu will be 
drawn. Vertical scrolling can occur when there are too many menu items to fit 
on the screen. Menus always occupy the full width of the window, but each 
menu item can take up one line only. At present, the function clips menus 
wider than the window because horizontal scrolling is not available yet. 


Paraaeters 
MenuInit requires these input and output parameters: 


usableRect The window-relative coordinates of the area that the menu 
can occupy. The usableRect is the maximum area of the 
window that the menu can take up. 


iteaCount The total number of separate menu entries. 


FUNCTION ItemStr A function supplied by the application programmer. Its 
index parameter represents the nth item on the menu, and 
the ItemStr function must return the string (i.e., string 
pointer) corresponding to that nth element of the menu. 
For example, ItemStr(S} should return a pointer to the 
string of the fifth item on the menu. The strings 
returned may have different maximum widths, but strings 
wider than the window will be clipped. Since each item 
can take up only a single line, the strings cannot contain 
embedded carriage returns. The SubStringLit function 
works well here. 


WARNING: Menulnit will dispose of the string returned by 
ItemStr; if necessary, make sure that ItemStr returns only 
a copy of the string. 

Returns 


MenuInit returns a MenuFormPtr to the menu that it creates, but it does not 
draw the menu. 
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Forminit 


FUNCTION Fora@init @ 
(usableRect: Rectangle; 
itemCount, 
maxChPerLabel, 
choiceLines: Integer; 
FUNCTION 
TtemStr(col,row: Integer; 
field: FieldPtr): StringPtr 
ds MenuFormPtr; 


Purpose and Operation 


This procedure creates and initializes @ form with a non-editable coluan of 
items and column of choices, which may or may not be editable. It needs to 
know the number of items on the form, the characteristics and setting of each 
item on the form, and the location on the window where the form will be drawn. 
See Figure 8-1, "MenuForm Pointer Structure." FormInit returns a MenuForaPtr 
to the form that it creates, but does not draw the form. 


Parameters 
Foralnit requires these input and output parameters: 
usableRect The window-relative coordinates of the area that the fora 


can occupy. The usableRect is the maximum area of the 
window that the form can take up. 


itemCount The total number of separate entries, where an entry in a 
form comprises a item and its choice setting. There are 
{itemCount x 2) fields in a form. 


maxChPerLabel The maximum number of characters in each itea, or 
equivalently, the width of the item coluan in characters. 
Note that the items cannot take up more than one line. 


choiceLines The maximum number of lines that the list of choice can 
occupy. FormInit interprets the value of choiceLines as 
follows: 


=O A band of space for the choices is NOT allocated or 
displayed. You showid set choicelines = 0 when no 
value fields have choices, so that the empty choice 
space will not be displayed. 


el The choices will be displayed as a horizontal list 
on a band of space above the form. If all of the 
choices cannot be displayed on the screen at once, 
horizontal scrolling becomes available 
automatically. 
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FUNCTION IteaStr 


>| If choiceLines is any positive integer greater than 
1, Forminit will display the choices vertically, 
one choice on a line, up to the maximum number of 
lines specified by choiceLines. Each choice can 
take up one line only; the function clips any 
choice wider than the window. 


If there are too many choices to fit in the 
vertical area defined by choiceLines, then the 
function automatically enables the choices to 
scroll vertically. 


A function supplied by the application. It should accept 
the column, row, and field pointer of a field in the fora, 
and then return the string that is the item (if it is a 
item field) or the default value (if it is a setting 
field). (No multi-line fields or strings containing 
carriage returns are allowed.} FormInit also enables the 
user's ItemStr function to change the editable and choice 
properties of each field. ItemStr must accept these 
parameters: 


col The column number of the desired field. 
row The row number of the desired field. 


field The pointer to the field designated by col and row. 
(Since it’s a pointer, the modified FldPtr is an 
implicit output of ItemStr, as well.) Forminit 
passes this pointer to the user's ItemStr function, 
allowing the application to aodify the editable and 
choice properties of each field. ItemStr can modify 
these properties by altering field*. kind. editable 
and field*.kind.choice, which otherwise default to 
False (non-editable, non-choice) in Forminit. 


Note that it would be meaningless to define a item 
field as an editable or chaice field, because the 
user should never be able to aave into a item 
field, by definition. 


The ItemStr function returns a StringPtr to the 

string of the desired field. It will return the string 
containing the item (if it is a item field) or the 
default value (if it is a setting field). {The string 
should not contain embedded carriage return or line feed 
characters.} If a setting field has no default setting, 
Item§tr should return an empty string with the maximua 
permissible length defined for that field. 
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HenuFormConfirmed 


FUNCTION MenuForaConfirmed 
(aenuFora: MenuForaPtr) 
keyProcess: Word3 
FUNCTION ItemStri(col, row: Integer; 


field: FieldPtr; 
de StringPtry 


FUNCTION ChoiceStricol, rows Integer; 


choice: Integers 
d: StringPtr; 


FUNCTION ChoicelInfo(col, row, choice: Integer; 


request: ChoiceRequest 
dy: Integer; 


FUNCTION ScrollKey- (ch: Char): UpdateKind; 
VAR selection: Integer; 


VAR ch: Char 
d: Boolean; 


Purpose and Operation 


This all-purpose function returns True when the user confirms a menu selection 
or new values on a form, It returns False if the user escapes out. 


P. ters 


MenuForeConfirmed requires these input and output parameters: 


menuFora 


FUNCTION ReadKey 


FUNCTION KeyPressed 


FUNCTION ItemStr 


A pointer to the menu or form to be edited, 


A function supplied by the application programmer. It 
enables the programmer to specify any function that 
reads a character from the console or any other input 
device. The function should return data of type Char. 
For example, ConCharIn would be a typical function. 


A function supplied by the application programmer, The 
programmer can specify any function to detect whether a 
console key has been pressed (or, for other types of 
input devices, to detect whether the input buffer 
contains a character). The function must return a 
boolean value. ConKeyPressed is a typical function ta 
supply here. 


The same function that was passed to Foralnit, above. 
It should accept the column, row, and field pointer of 
a field in the fora, and then return the default values 
of the setting fields. Jt acts here only to supply the 
default settings of editable-choice fields. 


NOTE: IF YOU ARE EDITING A MENU OR A FORM WITH NO 
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FUNCTION ChoiceStr 


EDITABLE CHOICE FIELDS, YOU MUST SUBSTITUTE A NIL 
FUNCTION FOR THIS FUNCTIONAL PARAMETER, The Function 
NilltemStr, given below, should be included as a 
Parameter here instead. 


ItemStr has these parameters: 
col The number of the desired column. 
row The number of the desired row, 


field The pointer to the field designated by col and 
row 


The ItemStr function returns a StringPtr representing 
the default value to the string of the desired field. 
If the setting field has no default value, ItemStr 
should return an empty string with the maximua 
permissible length defined for that field. 


A function supplied by the application programmer that 
returns a character string when it receives parameters 
that specify the column and row of the form, along with 
the choice. 


NOTE: THE ChoiceStr FUNCTION PARANETER 15 NEEDED ONLY 
FOR FORMS WITH CHOICE FIELDS. IF YOU ARE EDITING A 
MENU OR A FORM WITH NO CHOICE FIELDS, YOU MUST 
SUBSTITUTE A NIL FUNCTION FOR THIS FUNCTION PARAMETER. 
The function NilChoiceProc, given below, should be 
included as a parameter here instead. 


These are the parameters of ChoiceStr: 


col The column number of the desired field. NOTE: 
the ChoiceStr function will never be called for 
the item column (col = 1). As implemented now, 
it calls the function only with col = 2. 


row The row number of the desired field. 


choice The number of the choice for the given coluan 
and row for a setting field, if the field is a 
choice field. The program that calls ChoiceStr 
will never specify choice for a non-choice 
field. 


Given the above references to the fields of a fora, the 


ChoiceStr function should return pointers to these 
strings: 
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FUNCTION ChoicelIn#o 


Reference to: String returned: 


item field The item’s string 
value 

setting field--choice The string value 
of the current 
choice 


setting field--editable The string value 
of the field, 
a user‘’s typed 


response 
setting tield-- The string value 
choice or editable of the current 


choice, which can 
include a user's 
typed response 


Written by the application progammer, the function must 
return information about the choice field of any 
column, row, or choice of a form. 


NOTE: THE ChoiceInfo FUNCTION PARAMETER IS NEEDED ONLY 
FOR FORMS WITH CHOICE FIELDS. IF YOU ARE EDITING A 
MENU OR A FORM WITH NO CHOICE FIELDS, YOU MUST 
SUBSTITUTE A NIL FUNCTION FOR THIS FUNCTION PARAMETER. 
The function NilChoicelnfo, given below, should be 
included as a parameter here instead. 


The Choicelnfo function accepts these parameters: 


col The column number of the item which the 
outline is about to enter. 


row The row number of the item which the outline 
is about to enter. 


choice The number of the choice that the user @ade. 
It can be undefined or equal to zero when 
request = choiceCountRequest or 
choiceCurrentRequest. 


request These values of request determine what 
information is returned by ChoiceInfo: 


request = choiceCountRequest 

ChoiceIn¢o should return the total number of 
choices for the item of the form specified by 
"col" and “row”. 
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FUNCTIGN ScroliKey 


VAR selection 


VAR ch 


request = choiceCurrentRequest 

ChoiceInfo should return the number of the 
current choice for a given item. (The 
application is reading its choice value for 
the given item and passing it to the menu or 
form.) 


request = choiceSetCurrent 

The “choice” parameter represents the number 
of the choice designated by the highlighted 
box. The choice is associated with the ites 
specified by "coi" and "row®. The application 
should assign the value of “choice” to its own 
variable representing the choice values. The 
functional value that Choicelnfo returns is 
ignored. 


request = choiceLeavingltea 

The user has moved the outline from one itea 
to another. The application should check the 
values of “col” and "row" to see which item 
the user has moved out of. This is useful if 
the application needs to perform numeric 
conversions or error checking before allowing 
the user to confirm the form. 


request = choiceEnteringltes 

Receiving this request means that the outline 
is about to move to a different item (even if 
the next item has no choices). This lets your 
application validate the setting of the 
current item before moving the outline to the 
next item. 


This function is intended to implement “difficult case" 
scrolling of choices in a form. However, the Scrolikey 
operation is not available for use currentiy. For the 
present, you must include the NilScrolikey function 
(described later under Dummy Functions) in all your 
calls to MenuForaConfirmed. 


An output, it indicates which item the user selected 
from the menu. With a form, it returns the item (not 
the choice) that the user had moved to before 
confirming the form. 


The character that removed the user from the menu or 
form. These characters include other CODE~- commands, 
CONFIRM, ESC, and cancel (CODE-ESC}. The application 
can thus respond differently when the user quits, 
aborts, escapes, etc. 
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Returns 
MenuFormConfirmed returns a Boolean: it indicates that the user confirmed the 8 


menu or form and its values ( = True) or that the user aborted or escaped the 
menu or form without changing any of the data values. 
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NiilChorcePrac 


ke. ) FUNCTION NilChoiceProc{col,row: Integer; 
choice: Integer): StringPtr3 


Purpose and Operation 


A dummy functional parameter, which should be passed in place of the ChoiceStr 
functional parameter to MenuFormContirmed. It returns a StringPtr to nil. 


NiilChoiceiInfo 


FUNCTION NilChoiceinfo(col,row,choice: Integer; 
request:ChoiceRequest): Integer; 


Purpose and Operation 


A dummy functional parameter, which should be passed in place of the 
ChoiceInfo functional parameter to MenuFormConfirmed. This function always 


returns a value of zero. 


NilitemStr 
FUNCTION NilltemStr(col,row,choice: Integer; 
field: FieldPtr): StringPtr; 
Purpose and Operation 


A dummy functional parameter, which should be passed in place of the IteaStr 
functional parameter to NenuForaConfirmed. It returns a StringPtr to nil. 
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NiiScrolliKkey 
FUNCTION NilScrollKey(ch: Char): UpdateKind; ‘Gi 


Purpose and Operation 


A duamy functional parameter, which should be passed in place of the ScrollKey 
functional parameter to MenuFormConfirmed. This function always returns 
dontUpdate. 


MenuFormDispose 


FUNCTION MenuFormDispose(menuForm: MenuForaPtr): 
MenuFormPtr; 


Purpose and Operation 


This function deallocates the aenu or form pointed to by the MenuForaPtr. It 
disposes of everything, including all the text. There is no dontDisposeText 
option for the text strings because each instance of a menu or form is unique. 
MenuforaDispose always returns nil so that the MenuForaPtr to the disposed 
menu or form can be assigned the value of nil. 


C-14 Common Code Reference 


